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

# Fehlerbehandlung

> API-Fehlerantworten, Statuscodes und Fehlerformate verstehen

# Fehlerbehandlung

Alle RxScale APIs geben konsistente Fehlerantworten zurück. Diese Seite dokumentiert die Fehlerformate, HTTP-Statuscodes und häufige Fehlerszenarien.

## HTTP-Statuscodes

| Statuscode | Bedeutung            | Wann er auftritt                                                            |
| ---------- | -------------------- | --------------------------------------------------------------------------- |
| `200`      | OK                   | Erfolgreiche GET-, PATCH- oder POST-Anfrage                                 |
| `201`      | Created              | Ressource erfolgreich erstellt                                              |
| `204`      | No Content           | Ressource erfolgreich gelöscht                                              |
| `400`      | Bad Request          | Validierungsfehler, fehlende Parameter oder ungültiger Anfragekörper        |
| `401`      | Unauthorized         | Fehlende oder ungültige Authentifizierung (Token oder API-Schlüssel)        |
| `403`      | Forbidden            | Gültige Authentifizierung, aber unzureichende Berechtigungen                |
| `404`      | Not Found            | Ressource existiert nicht oder Sie haben keinen Zugriff darauf              |
| `409`      | Conflict             | Ressource existiert bereits (Duplikat)                                      |
| `422`      | Unprocessable Entity | Anfrage ist wohlgeformt, enthält aber ungültige Daten (z. B. korruptes PDF) |
| `429`      | Too Many Requests    | Ratenlimit überschritten                                                    |

<Warning>
  Aus Sicherheitsgründen gibt **unautorisierter Zugriff `404` anstelle von `403`** auf Ressourcen-Endpoints zurück. Dies verhindert, dass Angreifer herausfinden können, welche Ressourcen existieren. Wenn Sie einen `404` erhalten, überprüfen Sie sowohl die Korrektheit der Ressourcen-UID als auch die Berechtigungen Ihres API-Schlüssels.
</Warning>

## Fehlerantwort-Formate

RxScale APIs verwenden drei Fehlerantwort-Formate, abhängig vom Fehlertyp.

### Standardfehler

Die meisten Fehler geben einen einfachen Fehlerstring zurück:

```json theme={null}
{
  "error": "Resource not found"
}
```

Häufige Meldungen:

* `"Resource not found"` — Ressource existiert nicht oder Sie haben keinen Zugriff
* `"Bad request"` — Unerwarteter serverseitiger Fehler (Details werden intern protokolliert)
* `"Missing required parameters: from and to"` — Spezifische Information über fehlende Parameter

### Authentifizierungsfehler

Authentifizierungs- und Autorisierungsfehler geben einen Code und eine Beschreibung zurück:

```json theme={null}
{
  "code": "authorization_header_missing",
  "description": "Authorization header is expected"
}
```

| Code                           | Status | Beschreibung                                                               |
| ------------------------------ | ------ | -------------------------------------------------------------------------- |
| `authorization_header_missing` | 401    | Kein `Authorization`- oder `X-API-Key`-Header angegeben                    |
| `invalid_header`               | 401    | Fehlerhafter Authorization-Header oder nicht lesbares Token                |
| `token_expired`                | 401    | JWT-Token ist abgelaufen                                                   |
| `invalid_claims`               | 401    | Token-Audience oder -Issuer stimmt nicht überein                           |
| `invalid_api_key`              | 401    | API-Schlüssel nicht gefunden oder inaktiv                                  |
| `api_key_missing`              | 401    | `X-API-Key`-Header wird erwartet                                           |
| `permission_denied`            | 403    | API-Schlüssel hat nicht die erforderliche Berechtigung für diesen Endpoint |

### Validierungsfehler

Schema-Validierungsfehler geben feldbezogene Fehlerdetails zurück:

```json theme={null}
{
  "error": {
    "shop_uid": ["Missing data for required field."],
    "quantity": ["Not a valid integer."]
  }
}
```

Jeder Schlüssel ist der Feldname, und der Wert ist ein Array von Fehlermeldungen für dieses Feld. Korrigieren Sie alle aufgelisteten Felder und wiederholen Sie die Anfrage.

## Häufige Fehlerszenarien

<AccordionGroup>
  <Accordion title="401 — Fehlender API-Schlüssel">
    **Anfrage:**

    ```bash theme={null}
    curl https://api.rxscale.com/v1/management/products
    ```

    **Antwort:**

    ```json theme={null}
    {
      "code": "api_key_missing",
      "description": "X-API-Key header is expected"
    }
    ```

    **Lösung:** Fügen Sie den `X-API-Key`-Header in Ihre Anfrage ein.
  </Accordion>

  <Accordion title="403 — Unzureichende Berechtigungen">
    **Anfrage:** Versuch, mit einem schreibgeschützten API-Schlüssel zu schreiben.

    ```json theme={null}
    {
      "code": "permission_denied",
      "description": "API key lacks required permission: orders_write"
    }
    ```

    **Lösung:** Überprüfen Sie die Berechtigungen Ihres API-Schlüssels. Möglicherweise müssen Sie einen neuen Schlüssel mit den erforderlichen Berechtigungen erstellen.
  </Accordion>

  <Accordion title="404 — Ressource nicht gefunden">
    **Anfrage:** Zugriff auf eine Ressource mit einer ungültigen UID oder ohne Zugriffsberechtigung.

    ```json theme={null}
    {
      "error": "Resource not found"
    }
    ```

    **Lösung:** Überprüfen Sie, ob die Ressourcen-UID korrekt ist. Wenn Sie sicher sind, dass die UID gültig ist, prüfen Sie, ob Ihr API-Schlüssel die Berechtigung zum Zugriff auf die Ressource hat.
  </Accordion>

  <Accordion title="400 — Validierungsfehler">
    **Anfrage:** Übermittlung eines ungültigen Anfragekörpers.

    ```json theme={null}
    {
      "error": {
        "patient_data": {
          "first_name": ["Missing data for required field."],
          "date_of_birth": ["Not a valid integer."]
        }
      }
    }
    ```

    **Lösung:** Überprüfen Sie jedes im Fehler aufgelistete Feld und geben Sie gültige Werte an.
  </Accordion>

  <Accordion title="409 — Doppelte Ressource">
    **Anfrage:** Erstellung einer Ressource, die bereits existiert.

    ```json theme={null}
    {
      "error": "Pharmacy SKU already exists"
    }
    ```

    **Lösung:** Die Ressource existiert bereits. Verwenden Sie eine GET-Anfrage, um sie abzurufen, oder verwenden Sie PATCH, um sie zu aktualisieren.
  </Accordion>

  <Accordion title="429 — Ratenlimit überschritten">
    Sie haben das Ratenlimit überschritten. Warten Sie, bevor Sie es erneut versuchen. Siehe [Ratenbegrenzungen](/de/rate-limits) für Details und bewährte Praktiken.
  </Accordion>
</AccordionGroup>

## Bewährte Praktiken

<AccordionGroup>
  <Accordion title="Prüfen Sie immer zuerst den HTTP-Statuscode">
    Der Statuscode zeigt Ihnen die Fehlerkategorie. Analysieren Sie den Antwortkörper für Details erst nach der Prüfung des Statuscodes.
  </Accordion>

  <Accordion title="Behandeln Sie 404 defensiv">
    Ein `404` kann bedeuten, dass die Ressource nicht existiert ODER dass Sie keinen Zugriff haben. Nehmen Sie nicht an, welches der Fall ist — überprüfen Sie sowohl die Berechtigungen Ihres API-Schlüssels als auch die Ressourcen-UID.
  </Accordion>

  <Accordion title="Implementieren Sie exponentielles Backoff für 429">
    Wenn das Ratenlimit erreicht ist, warten Sie und wiederholen Sie die Anfrage mit zunehmenden Verzögerungen. Wiederholen Sie nie sofort in einer engen Schleife.
  </Accordion>

  <Accordion title="Protokollieren Sie die vollständige Fehlerantwort">
    Protokollieren Sie zum Debuggen den gesamten Antwortkörper einschließlich Statuscode und Headern. Der RxScale-Support kann nach diesen Details fragen.
  </Accordion>
</AccordionGroup>