Zum Hauptinhalt springen
Eine Anfrage, die die API ablehnt, liefert einen HTTP-Fehlerstatus und diesen Umschlag:
code ist stabil; verzweigen Sie danach. message ist für Menschen gedacht und kann sich ändern. details ist vorhanden, wenn es etwas zu ergänzen gibt: meist ein Array aus { field, message } bei einem Validierungsfehler oder ein Objekt wie { "id": "..." } oder { "retryAfterSec": 5, "retryable": true }. Ein Task, der angenommen wird und später fehlschlägt, erzeugt keinen HTTP-Fehler. Er meldet stattdessen einen Fehlercode fehlgeschlagener Tasks.

Fehlercodes für Anfragen

Verzweigen Sie lieber nach error.code als nach dem Status: VALIDATION_ERROR erscheint sowohl als 400 als auch als 422. Ein 429 bedeutet, dass Sie eines Ihrer eigenen Limits erreicht haben; ein 503, dass uns gerade Kapazität fehlt.

Retry-After

Bei POST /v1/async/task, POST /v1/async/task/batch und POST /v1/async/task/grid trägt jede 429- und 503-Antwort einen Retry-After-Header in Sekunden. Die meisten dieser Codes tragen zusätzlich details.retryAfterSec und details.retryable: true. 429-Antworten des Edge-Anfragelimits tragen keines von beiden. Siehe Credits und Limits.

Größenlimits für den Body

Ablehnung wegen der Region

REGION_UNSUPPORTED wird entschieden, bevor der Task eingereiht wird. Sie erfahren es also sofort, statt darauf zu warten, dass der Task fehlschlägt:
Welche Engines welche Länder bedienen, steht unter Regionen und Standort.

Fehler pro Eintrag in Batches und Rastern

Bei POST /v1/async/task/batch liefert eine wohlgeformte Anfrage 200, auch wenn Einträge fehlschlagen. Der Status beschreibt die Anfrage, results[].success jeden Task, und ein fehlgeschlagener Eintrag trägt dasselbe Objekt { code, message, details, timestamp } wie ein Anfragefehler:
Ein Eintrag, der mit einem 429-Code, QUEUE_BACKPRESSURE oder SERVER_OVERLOADED fehlgeschlagen ist, trägt seine Wartezeit in details.retryAfterSec. Die Anfrage selbst scheitert nur dann mit 400, 413, 429 oder 503, wenn der ganze Batch abgelehnt wird. POST /v1/async/task/grid meldet abgelehnte Punkte auf dieselbe Weise in points[]. POST /v1/batches lehnt den ganzen Batch mit 400 ab, wenn ein Eintrag ungültig ist, und speichert Einträge, die die Annahme ablehnt, etwa wegen INSUFFICIENT_CREDITS, als REJECTED. Ein Eintrag, dessen idempotencyKey zu einem vor dem Batch erstellten Task passte, erscheint als FAILED mit TASK_NOT_RETAINED, sobald dieser Task nicht mehr aufbewahrt wird. Siehe Batches und Raster.

Fehlercodes fehlgeschlagener Tasks

Ein Task, der nach dem Einreihen fehlschlägt, endet in FAILED. Polling liefert einen error-String auf oberster Ebene, nicht das Objekt der Anfragefehler:
Der Webhook trägt denselben String in response.error. Der String beginnt mit einem Code; verzweigen Sie danach.

Änderungen an Task-Fehlercodes