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

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.

​

Fehlerantwort-Formate

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

​

Standardfehler

Die meisten Fehler geben einen einfachen Fehlerstring zurück:

{
  "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:

{
  "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:

{
  "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

401 — Fehlender API-Schlüssel

Anfrage:

curl https://api.rxscale.com/v1/management/products

Antwort:

{
  "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.

403 — Unzureichende Berechtigungen

Anfrage: Versuch, mit einem schreibgeschützten API-Schlüssel zu schreiben.

{
  "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.

404 — Ressource nicht gefunden

Anfrage: Zugriff auf eine Ressource mit einer ungültigen UID oder ohne Zugriffsberechtigung.

{
  "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.

400 — Validierungsfehler

Anfrage: Übermittlung eines ungültigen Anfragekörpers.

{
  "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.

409 — Doppelte Ressource

Anfrage: Erstellung einer Ressource, die bereits existiert.

{
  "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.

429 — Ratenlimit überschritten

Sie haben das Ratenlimit überschritten. Warten Sie, bevor Sie es erneut versuchen. Siehe Ratenbegrenzungen für Details und bewährte Praktiken.

​

Bewährte Praktiken

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.

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.

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.

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.