Wenn etwas schiefgeht.
Fehler kommen als JSON-Umschlag zurück, mit einem stabilen type, einer menschenlesbaren Meldung und einer request_id, die Sie uns bei der Meldung eines Problems mitschicken können.
{"type": "error", "error": {
"type": "authentication_error",
"message": "Invalid or revoked API key.",
"request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
}}| HTTP | Bedeutung | Was zu tun ist |
|---|---|---|
| 400 | Fehlerhafter Body (fehlendes Feld oder falscher Typ) | Die Meldung nennt das genaue Feld - korrigieren und erneut versuchen. |
| 401 | Ungültiger oder widerrufener API-Schlüssel | Prüfen Sie den Schlüssel; stellen Sie in der Konsole einen neuen aus. |
| 402 | Guthaben aufgebraucht, keine Karte hinterlegt oder Stufenlimit erreicht | Laden Sie in der Konsole Guthaben auf oder hinterlegen Sie eine Karte. Die Antwort enthält balance_cents und floor_cents, sodass Sie erkennen, was Sie gestoppt hat. |
| 404 | Erinnerung, Store oder Bild existiert nicht | Prüfen Sie die id. get_image antwortet auch dann mit 404, wenn die Erinnerung zwar existiert, aber kein Bild trägt. |
| 409 | Dieser Name ist bereits vergeben | Store- und Workspace-Namen sind innerhalb eines Kontos eindeutig - wählen Sie einen anderen. |
| 413 | Request-Body über 10MB | Base64 ist rund 33% größer als die Datei, die es kodiert - verkleinern Sie das Bild also, bevor Sie es kodieren. |
| 429 | Rate-Limit erreicht | Das SDK wiederholt diese Anfragen bereits für Sie, mit Backoff und Jitter, und beachtet dabei Retry-After. Wenn Sie einen solchen Fehler erhalten, sind die Wiederholungen aufgebraucht - senken Sie die Zahl gleichzeitiger Anfragen, statt eine eigene Schleife darum zu legen. |
| 501 | Die Engine dieses Modells implementiert diesen Endpunkt nicht | Bilder und Revisionsverlauf benötigen eine neuere Engine. GET /api/v1/models listet auf, welches Modell was bedient. |
| 5xx | Serverseitiges Problem | Mit Backoff erneut versuchen, aber nicht blind. Das SDK wiederholt einen 5xx hier nicht automatisch, denn jeder Aufruf dieser API ist ein POST und der Server hat Ihre Anfrage möglicherweise bereits gespeichert. Senden Sie sie mit einem Idempotenzschlüssel erneut, damit eine Wiederholung nicht doppelt schreiben kann, und geben Sie die request_id an, wenn Sie uns kontaktieren. |
Jeder Fehler ist ein WosError, und jeder Status hat zusätzlich eine eigene Klasse - BadRequestError, AuthenticationError, PaymentRequiredError, NotFoundError, ConflictError, RateLimitError, ServerError, APIConnectionError. Fangen Sie die ab, die Sie behandeln wollen, statt Zahlen zu vergleichen.
# SDK error handling (Python) from wontopos import Client, WosError, RateLimitError, PaymentRequiredError try: mem.search("...", user_id="alice") except PaymentRequiredError: ... # 402 - top up except RateLimitError: ... # 429 - the SDK already retried; slow down except WosError as e: ... # e.status, e.message, e.request_id except (ValueError, TypeError): ... # never left the client
Manche Fehler erreichen uns nie. Der API-Schlüssel, die Store-id, der Idempotenzschlüssel und das Bild werden alle geprüft, bevor die Anfrage hinausgeht, und dabei wird ValueError oder TypeError ausgelöst - nicht WosError. Ein except WosError allein fängt sie nicht ab.
Rate-Limits gelten pro Konto, geteilt über alle Ihre Schlüssel, und skalieren mit Ihrer Stufe - siehe Nutzungsstufen. Die Nutzung Ihres Kontos sehen Sie in der Konsole.