> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winampay.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP error codes and standard error response format.

## Standard error format

All error responses use a consistent JSON format:

```json theme={null}
{
  "detail": "Explanatory error message"
}
```

For `422` (validation errors), `detail` is an array:

```json theme={null}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "msisdn"],
      "msg": "Field required"
    }
  ]
}
```

## HTTP error codes

| Code  | Situation                                                                                                                           | Example `detail`                                                 |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `200` | Success (or idempotency hit)                                                                                                        | —                                                                |
| `400` | Invalid parameter                                                                                                                   | `"Unknown operator: 'wave'. Accepted values: mtn, orange."`      |
| `401` | Missing or invalid API key                                                                                                          | `"Invalid or missing API key."`                                  |
| `404` | Transaction not found                                                                                                               | `"Transaction not found: 7c9e6679-..."`                          |
| `422` | Validation error: missing field, wrong type, or MSISDN prefix contradicting `operator` (MTN: 67x/68x/650-654 · Orange: 69x/655-659) | Array of validation errors, or string detail for prefix mismatch |
| `503` | No provider available for this operator                                                                                             | `"No provider available for operator=mtn."`                      |
| `500` | Internal error                                                                                                                      | `"Internal error."`                                              |

## Common errors

<AccordionGroup>
  <Accordion title="401 — Invalid or missing API key">
    Your `X-API-Key` header is missing or incorrect.

    ```json theme={null}
    { "detail": "Invalid or missing API key." }
    ```

    Contact [support@eins-innovativ.de](mailto:support@eins-innovativ.de) to obtain or reset your API key.
  </Accordion>

  <Accordion title="400 — Unknown operator">
    The `operator` field must be `"mtn"` or `"orange"`.

    ```json theme={null}
    { "detail": "Unknown operator: 'wave'. Accepted values: mtn, orange." }
    ```

    Use `POST /api/v1/msisdn/detect` to automatically detect the operator from the MSISDN.
  </Accordion>

  <Accordion title="422 — Validation error">
    A required field is missing or has an invalid type.

    ```json theme={null}
    {
      "detail": [
        { "type": "missing", "loc": ["body", "reference"], "msg": "Field required" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="503 — No provider available">
    All providers for the requested operator are currently unavailable (feature flag disabled or degraded).

    ```json theme={null}
    { "detail": "No provider available for operator=mtn." }
    ```

    Check `GET /api/v1/CM/providers/status` for real-time provider health.
  </Accordion>
</AccordionGroup>