Fehlerbehandlung
RxScale APIs verwenden überwiegend dieselben Fehlerformate. Diese Seite dokumentiert die Fehlerformate, HTTP-Statuscodes und häufige Fehlerszenarien und nennt die Stellen, an denen eine API abweicht.HTTP-Statuscodes
Fehlerantwort-Formate
RxScale APIs verwenden drei Fehlerantwort-Formate, abhängig vom Fehlertyp.Standardfehler
Die meisten Fehler geben einen einfachen Fehlerstring zurück:"Resource not found"— Ressource existiert nicht oder Sie haben keinen Zugriff"Bad request"— Allgemeiner Fehler; der Grund wird nur in den Protokollen von RxScale festgehalten, nicht in der Antwort. In der External Pharmacy API deckt er auch Anfragen ab, die RxScale ablehnt, etwa die Statusänderung einer stornierten Bestellung — siehe Fehlerantworten der External Pharmacy API"Missing required parameters: from and to"— Spezifische Information über fehlende Parameter
code — siehe Reason-Codes der Public API.
Authentifizierungsfehler
Authentifizierungsfehler sowie Berechtigungsfehler in der Management API und der Public API geben einen Code und eine Beschreibung zurück:
Die External Pharmacy API verwendet
permission_denied nicht: Ein Schlüssel ohne die erforderliche Berechtigung erhält 403 mit {"error": "Permission denied"}. Siehe Fehlerantworten der External Pharmacy API.
Die Public API gibt denselben Text zusätzlich unter error zurück, sodass die Meldung bei jedem Fehler unter demselben Schlüssel steht:
Validierungsfehler
Schema-Validierungsfehler geben feldbezogene Fehlerdetails zurück:error so verschachtelt wie der Anfragekörper. Die Public API ergänzt code und eine flache details-Map, damit Sie die Verschachtelung nicht durchlaufen müssen: Jeder Schlüssel ist der Pfad eines abgelehnten Feldes in Punktschreibweise.
lines.0.quantity ist die quantity der ersten Position; Listenpositionen beginnen bei 0. Eine Meldung, die den Anfragekörper als Ganzes betrifft, steht unter _schema.
Reason-Codes der Public API
Jeder Fehler, den die Public API als JSON zurückgibt, enthält nebenerror einen stabilen
code. Verzweigen Sie über code, nicht über den HTTP-Status oder den Text von error:
Ein Status deckt mehrere Gründe ab, und der Wortlaut von error kann sich ändern.
Zwei dieser Codes verwenden
403. Dieser Status wird auch verwendet, wenn Ihrem API-Schlüssel eine Berechtigung fehlt; diese Antwort trägt code: "permission_denied". Verzweigen Sie über code.
Der Rezept-Checkout verwendet zusätzlich duplicate_prescription_injection und
order_already_exists (beide 409); sie sind bei diesem Endpunkt beschrieben. Eine Antwort
ist älter als die Codes und hat keinen: Ein ungültiges oder unsigniertes Rezept-PDF wird mit
422 und {"errors": {"message": "..."}} beantwortet.
Positionen
unknown_sku, insufficient_stock und product_unavailable_in_shop benennen die
betroffenen Positionen in einem lines-Array, mit Ihren eigenen Identifiern und der
angeforderten quantity. Eine Position, die in Ordnung ist, erscheint dort nie.
external_id ist Ihre eigene Produktkennung für diese SKU, oder null, wenn die SKU für
Ihren Anbieter nicht gemappt ist. Am weed.de-Endpunkt ist es die externalId, die weed.de gesendet hat. sku_uid ist null, wenn sich eine external_id
überhaupt keiner SKU zuordnen ließ. Bei product_unavailable_in_shop fehlt lines,
wenn die Ablehnung keiner einzelnen Position zugeordnet werden kann — ein fehlendes lines
bedeutet „eines dieser Produkte”, nicht „kein Problem”.
Bei unknown_sku wird ein Warenkorb mit einer gültigen und einer unbekannten Position als
Ganzes abgelehnt, und lines enthält nur die unbekannte Position:
insufficient_stock wird auf dem Reservierungs-Endpunkt ausgelöst, bevor eine Draft Order
angelegt wird — eine abgelehnte Reservierung hinterlässt also nichts. RxScale gibt diesen
Code nur zurück, wenn die Shopify-Variante Bestand führt und inventoryPolicy DENY hat:
der Shop erlaubt keinen Verkauf über den vorhandenen Bestand hinaus. Bei
inventoryPolicy CONTINUE ist Überverkauf erlaubt: die Draft Order wird angelegt und
der Endpunkt antwortet mit 200, auch wenn die angeforderte Menge über dem vorhandenen
Bestand liegt. Eine Variante ohne Bestandsführung wird genauso behandelt. Shopify meldet
für diese Varianten trotzdem inventoryPolicy DENY, und es gibt keine Bestandszahl;
RxScale lehnt sie nicht ab.
quantity ist die angeforderte Menge, available_stock der aktuell gedeckte Bestand —
available_stock ist also immer kleiner. Gedeckte Zeilen, Zeilen deren Variante
Überverkauf erlaubt (inventoryPolicy CONTINUE), und Zeilen ohne Bestandsführung
erscheinen nicht. Derselbe
Feldname available_stock wird von
POST /v2/{service}/products/{shop_identifier}/live-stock verwendet, der die vorhandene
Menge ohne Reservierungsversuch meldet. Diese Live-Stock-Antwort wendet die
inventoryPolicy-Regel oben nicht an.
Es können künftig weitere
code-Werte hinzukommen. Behandeln Sie einen unbekannten code
als allgemeinen Fehler, anstatt die Antwort zu verwerfen.Fehlerantworten der External Pharmacy API
Die External Pharmacy API gibt die folgenden Fehlerantworten zurück. Verlassen Sie sich auf den HTTP-Statuscode und behandeln Sie den Antwortkörper als zusätzliche Information.{"error": "Bad request"} ist ein allgemeiner Fehler. Der Grund wird nur in den Protokollen von RxScale festgehalten, nicht in der Antwort. Neben unerwarteten Fehlern deckt er einen Wert für page oder limit ab, der keine ganze Zahl ist (Bestell- und Auszahlungslisten).
Wiederholen Sie solche Anfragen nicht automatisch. Wenden Sie sich an den RxScale-Support und nennen Sie Endpoint, HTTP-Methode, Zeitpunkt und Anfragekörper (ohne Geheimnisse wie Ihren API-Schlüssel).
PATCH /pharmacy_orders/{uid}/complete_order liest seinen Anfragekörper auch ohne Content-Type-Header und gibt die Content-Type-Meldung oben daher nie zurück. Der Endpoint hat zwei weitere 400-Varianten:
{"error": {...}, "pharmacy": {"uid": "...", "display_name": "..."}}— der Anfragekörper hat die Validierung nicht bestanden, zum Beispiel wegen eines nicht unterstütztencarrier.pharmacynennt die Apotheke, für die die Anfrage gestellt wurde.{"error": "<message>"}— Sie haben Tracking-Links für eine bereits abgeschlossene Bestellung gesendet.
Häufige Fehlerszenarien
401 — Fehlender API-Schlüssel
401 — Fehlender API-Schlüssel
Anfrage:Antwort:Lösung: Fügen Sie den
X-API-Key-Header in Ihre Anfrage ein.403 — Unzureichende Berechtigungen
403 — Unzureichende Berechtigungen
Anfrage: Versuch, mit einem schreibgeschützten API-Schlüssel zu schreiben.Management API und Public API — erkennen Sie diesen Fehler an External Pharmacy API: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.
code; description ist ein lesbarer Text:404 — Ressource nicht gefunden
404 — Ressource nicht gefunden
Anfrage: Zugriff auf eine Ressource mit einer ungültigen UID oder ohne Zugriffsberechtigung.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
400 — Validierungsfehler
Anfrage: Übermittlung eines ungültigen Anfragekörpers.Lösung: Überprüfen Sie jedes im Fehler aufgelistete Feld und geben Sie gültige Werte an.
409 — Doppelte Ressource
409 — Doppelte Ressource
Anfrage: Erstellung einer Ressource, die bereits existiert.Lösung: Die Ressource existiert bereits. Verwenden Sie eine GET-Anfrage, um sie abzurufen, oder verwenden Sie PATCH, um sie zu aktualisieren.
413 — Anfragekörper zu groß
413 — Anfragekörper zu groß
Anfrage: Ein Körper über dem Limit von 32 MiB.Lösung: Verteilen Sie die Daten auf mehrere Anfragen.
429 — Ratenlimit überschritten
429 — Ratenlimit überschritten
Sie haben das Ratenlimit überschritten. Der Antwortkörper ist HTML, kein JSON:Es werden weder ein
Retry-After- noch X-RateLimit-*-Header gesendet.
Lösung: Warten Sie mindestens eine Sekunde — ein volles Ratenlimit-Fenster — und
versuchen Sie es dann erneut. Siehe Ratenbegrenzungen für Details
und bewährte Praktiken.Bewährte Praktiken
Prüfen Sie immer zuerst den HTTP-Statuscode
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
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
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 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.