Zum Hauptinhalt springen

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

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.
Einige Antworten sind überhaupt kein JSON: Ein ratenbegrenzter 429 sowie der 404 oder 405 für einen Pfad oder eine HTTP-Methode, die eine API nicht kennt, liefern Content-Type: text/html mit einer kurzen HTML-Fehlerseite. Verzweigen Sie immer über den HTTP-Statuscode, bevor Sie den Antwortkörper parsen — ein Client, der bedingungslos response.json() aufruft, scheitert genau an der Antwort, für die seine Wiederholungslogik geschrieben wurde. Siehe Ratenbegrenzungen.

Standardfehler

Die meisten Fehler geben einen einfachen Fehlerstring zurück:
Häufige Meldungen:
  • "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
In der Public API enthält jeder Fehler zusätzlich einen 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:
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. Bei einem Feld innerhalb einer Liste oder eines Objekts ist 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 neben error 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.
Senden Sie bei jeder Reservierung eine external_reservation_id mit. Eine Anfrage, die Sie wiederholen, weil die Antwort nicht angekommen ist, wird dann mit der bereits bestehenden Draft Order beantwortet. Ein Fall bleibt: Nach einem internal_error ist der Ausgang nicht bekannt. In seltenen Fällen wurde die Draft Order vor dem Fehler noch angelegt, ohne dass RxScale sie festhalten konnte; eine Wiederholung reserviert den Bestand dann ein zweites Mal. Diese erste Reservierung wird nach 24 Stunden von selbst freigegeben. Dasselbe kann, noch seltener, nach einem shopify_error passieren.

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ützten carrier. pharmacy nennt 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

Anfrage:
Antwort:
Lösung: Fügen Sie den X-API-Key-Header in Ihre Anfrage ein.
Anfrage: Versuch, mit einem schreibgeschützten API-Schlüssel zu schreiben.Management API und Public API — erkennen Sie diesen Fehler an code; description ist ein lesbarer Text:
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.
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.
Anfrage: Übermittlung eines ungültigen Anfragekörpers.
Lösung: Überprüfen Sie jedes im Fehler aufgelistete Feld und geben Sie gültige Werte an.
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.
Anfrage: Ein Körper über dem Limit von 32 MiB.
Lösung: Verteilen Sie die Daten auf mehrere Anfragen.
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

Der Statuscode zeigt Ihnen die Fehlerkategorie. Analysieren Sie den Antwortkörper für Details erst nach der Prüfung des Statuscodes.
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.
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 zum Debuggen den gesamten Antwortkörper einschließlich Statuscode und Headern. Der RxScale-Support kann nach diesen Details fragen.