Lumenaza API Error Codes and Troubleshooting Guide

The Lumenaza API returns standard HTTP status codes for every request. This page explains each code you may encounter, describes the error response formats, lists common validation errors with example payloads, and provides a debugging checklist to help you resolve issues quickly.

HTTP Status Codes

The Lumenaza API uses standard HTTP status codes to indicate the outcome of every request. The table below lists all codes you may encounter.

Status Code	Meaning
`200 OK`	The request succeeded. Response body contains the requested or updated resource.
`201 Created`	A new resource was successfully created. Response body contains the new resource.
`202 Accepted`	The request was accepted and an asynchronous workflow has been triggered.
`204 No Content`	The request succeeded (typically a `DELETE`). No response body is returned.
`300 Multiple Choices`	The submitted address matched multiple entries (offer calculator / address lookup).
`400 Bad Request`	Input validation failed. The response body contains field-level error messages (see below).
`401 Unauthorized`	The `Authorization` token is missing, invalid, or expired.
`403 Forbidden`	The action is not permitted — e.g. a product switch is not allowed, or credit check is disabled.
`404 Not Found`	The requested resource does not exist.
`409 Conflict`	A conflicting in-flight workflow already exists for this resource.
`500 Internal Server Error`	An unexpected server-side failure occurred. Retry the request or contact Lumenaza support.

Error Response Formats

400 Bad Request — Field-Level Validation Errors

When input validation fails, the response body is a JSON object whose keys are the names of the invalid fields and whose values are human-readable error messages:

{
  "email": "This field must be unique.",
  "bank_data_iban": "Enter a valid IBAN."
}

Multiple fields can fail simultaneously; all violations are returned in a single response so you can correct them in one round-trip.

Detail Errors

Some errors — including 401, 403, 404, and certain 400 cases — use a flat detail key instead of field names:

{
  "detail": "Contract ID not found in database."
}

404 Not Found

{
  "detail": "Contract ID not found in database."
}

Common 400 Validation Errors

The table below lists frequently encountered validation errors, the field(s) involved, and an example error message.

Field(s)	Scenario	Example Error Message
`email`	Email address already registered	`"This field must be unique."`
`saas_customer_id` / `saas_contract_id`	Supplied external ID already exists in the system	`"saas_contract_id must be unique."`
`preferred_delivery_start`	Date is more than 2 weeks in the future	`"Delivery start cannot be more than 2 weeks in the future."`
`preferred_delivery_start`	Date is more than 6 weeks in the past	`"Delivery start cannot be more than 6 weeks in the past."`
`bank_data_iban`	IBAN fails checksum or format validation	`"Enter a valid IBAN."`
`bank_data_iban`	IBAN is not a German IBAN (DE prefix) where required	`"Only German IBANs (DE…) are accepted."`
`meteringpoint_id`	Market location ID is not exactly 11 digits	`"Ensure this field has exactly 11 characters."`
`meteringpoint_id`	Market location ID contains non-numeric characters	`"Enter a valid market location ID (digits only)."`
`tariff_type`	Product/tariff not found in the system	`"Product not found."`
`tariff_type`	Product exists but is not permitted for this contract	`"This product is not allowed for the given contract parameters."`
`sepa_date`	SEPA mandate date is set in the future	`"sepa_date must be today or in the past."`
`order_date`	Order date is set in the future	`"order_date cannot be in the future."`
`previous_provider`	Required for supplier-switch (`E03`) but not supplied	`"This field is required for subscription_reason E03."`
`company_name`	`is_business` is `true` but `company_name` is missing	`"company_name is required when is_business is true."`

Detailed Error Scenarios

401 Unauthorized — Invalid or Expired Token

Returned when the Authorization header is absent, malformed, or contains an expired Bearer token.Response:

{
  "detail": "Authentication credentials were not provided."
}

Fix: Verify the Authorization: Bearer <token> header is present and that the token has not expired. Contact Lumenaza to reissue credentials if needed.

403 Forbidden — Action Not Permitted

Returned when the authenticated user does not have permission to perform the requested action. Common causes:

Attempting a product switch that is not configured for the contract type.
Calling an endpoint that requires credit check functionality when it is not enabled for your account.

Response:

{
  "detail": "You do not have permission to perform this action."
}

Fix: Contact Lumenaza to confirm which features are enabled for your SaaS contract.

409 Conflict — In-Flight Workflow

Returned when you attempt to trigger a workflow (e.g. a contract termination or tariff switch) while an identical workflow is already being processed for the same resource.Response:

{
  "detail": "A workflow of this type is already in progress for this contract."
}

Fix: Wait for the existing workflow to complete before submitting a new one. Poll the relevant status endpoint to monitor progress.

300 Multiple Choices — Address Ambiguity

Returned by the offer calculator when the submitted address matches more than one entry in the address database.Response: A list of candidate addresses for the user to select from.Fix: Present the choices to the end user and re-submit the request with the fully qualified address from the returned list.

500 Internal Server Error

Indicates an unexpected failure on Lumenaza’s infrastructure.Fix:

Wait briefly and retry the request with exponential back-off.
If the error persists, capture the full request/response (excluding secrets) and contact Lumenaza support with the timestamp and endpoint path.

Debugging Checklist

Follow these steps when diagnosing an unexpected error:

Log the full response body. The API always returns a JSON body for error responses (except 204). The field-level keys tell you exactly which inputs need to change.
Check field-specific messages. A single 400 response may contain errors for multiple fields. Iterate over all keys in the response object, not just the first one.
Distinguish {"field": "..."} from {"detail": "..."}.
- Field-keyed responses indicate input validation failures — fix the payload.
- detail-keyed responses indicate authentication, permission, or server issues — these usually cannot be resolved by changing the request body alone.
Verify date constraints. preferred_delivery_start, sepa_date, and order_date all have strict relative-date rules. Ensure your system clock is correct and that you are sending dates in YYYY-MM-DD format (UTC).
Confirm uniqueness constraints. email, saas_customer_id, and saas_contract_id must be globally unique. Check your records before retrying a failed create request.
Test in the sandbox first. Use https://api.test.lumenaza.de/ to validate your integration without affecting production data.

When contacting Lumenaza support about an error, always include: the endpoint path, the HTTP method, the full (sanitised) request body, the HTTP status code received, and the full response body.

Overview

API Endpoints

Lumenaza API Error Codes and Troubleshooting Guide

HTTP Status Codes

Error Response Formats

400 Bad Request — Field-Level Validation Errors

Detail Errors

404 Not Found

Common 400 Validation Errors

Detailed Error Scenarios

Debugging Checklist

​HTTP Status Codes

​Error Response Formats

​400 Bad Request — Field-Level Validation Errors

​Detail Errors

​404 Not Found

​Common 400 Validation Errors

​Detailed Error Scenarios

​Debugging Checklist

HTTP Status Codes

Error Response Formats

400 Bad Request — Field-Level Validation Errors

Detail Errors

404 Not Found

Common 400 Validation Errors

Detailed Error Scenarios

Debugging Checklist