> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenaza.de/llms.txt
> Use this file to discover all available pages before exploring further.
# Lumenaza API Error Codes and Troubleshooting Guide
> HTTP status codes, field-level validation error formats, common 400 error examples, and step-by-step debugging guidance for the Lumenaza API.
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:
```json theme={null}
{
"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:
```json theme={null}
{
"detail": "Contract ID not found in database."
}
```
### 404 Not Found
```json theme={null}
{
"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
Returned when the `Authorization` header is absent, malformed, or contains an expired Bearer token.
**Response:**
```json theme={null}
{
"detail": "Authentication credentials were not provided."
}
```
**Fix:** Verify the `Authorization: Bearer ` header is present and that the token has not expired. Contact Lumenaza to reissue credentials if needed.
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:**
```json theme={null}
{
"detail": "You do not have permission to perform this action."
}
```
**Fix:** Contact Lumenaza to confirm which features are enabled for your SaaS contract.
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:**
```json theme={null}
{
"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.
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.
Indicates an unexpected failure on Lumenaza's infrastructure.
**Fix:**
1. Wait briefly and retry the request with **exponential back-off**.
2. 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:
1. **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.
2. **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.
3. **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.
4. **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).
5. **Confirm uniqueness constraints.** `email`, `saas_customer_id`, and `saas_contract_id` must be globally unique. Check your records before retrying a failed create request.
6. **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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.