EntwicklerdokumentationErste Schritte
Fehler
Ein Fehlerformat, stabile Codes, klare Regeln für Wiederholungen.
Jede Antwort außerhalb von 2xx hat dieselbe Struktur. Werten Sie error.code aus, nie message.
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| Feld | Inhalt |
|---|---|
code | Stabil, snake_case |
message | Englisch, für Logs |
request_id | Auch in X-Request-Id. Geben Sie sie beim Support an |
details[] | Bei 400/422: path, code, message pro Problem |
Codes
| Status | Code | Bedeutung | Abhilfe | Wiederholbar |
|---|---|---|---|---|
| 400 | invalid_json | Der Body ist kein gültiges JSON, oder ein Feld hat den falschen Typ. | Korrigieren Sie den Anfrage-Body. | Nein |
| 401 | unauthorized | API-Schlüssel fehlt, ist fehlerhaft oder unbekannt. | Senden Sie Authorization: Bearer cd_live_…; prüfen Sie, ob der Schlüssel vollständig kopiert wurde. | Nein |
| 401 | key_revoked | Der Schlüssel wurde widerrufen. | Erstellen Sie in der Entwicklerkonsole einen neuen Schlüssel. | Nein |
| 401 | key_expired | Der Schlüssel ist abgelaufen. | Erstellen Sie in der Entwicklerkonsole einen neuen Schlüssel. | Nein |
| 402 | insufficient_credits | Die verfügbaren Credits decken nicht einmal den günstigsten möglichen Lauf dieses Jobs. | Kaufen Sie ein Credit-Paket oder warten Sie auf die monatlichen Credits; es wurde nichts abgebucht. | Nein |
| 403 | ip_not_allowed | Die aufrufende IP-Adresse steht nicht auf der Allowlist des Schlüssels. | Rufen Sie die API von einer erlaubten IP-Adresse auf oder passen Sie die Allowlist an. | Nein |
| 403 | subscription_inactive | Die Organisation hat kein aktives Abonnement, das die API enthält. | Verlängern Sie das Abonnement. | Nein |
| 403 | account_inactive | Die Organisation ist gesperrt oder hat keinen Inhaber mit aktivem Konto. | Wenden Sie sich an den Support. | Nein |
| 403 | scope_missing | Dem Schlüssel fehlt eine Berechtigung, die dieser Endpoint benötigt. | Verwenden Sie einen Schlüssel mit der nötigen Berechtigung (pack:write, jobs:read, account:read, resources:read, resources:write). | Nein |
| 403 | preset_read_only | Vordefinierte Fahrzeuge können weder geändert noch gelöscht werden. | Legen Sie ein eigenes Fahrzeug an: POST /v1/vehicles. | Nein |
| 403 | plan_limit_reached | Der Tarif der Organisation erlaubt keine weiteren Projekte oder Artikel. | Löschen Sie nicht mehr benötigte Projekte oder wechseln Sie zu einem größeren Tarif. | Nein |
| 404 | not_found | Kein /v1-Endpoint hat diese Methode und diesen Pfad. | Gleichen Sie Methode und Pfad mit der Endpoint-Liste ab. | Nein |
| 404 | job_not_found | Kein Job mit dieser ID in Ihrer Organisation. | Prüfen Sie die ID. | Nein |
| 404 | vehicle_not_found | Kein Fahrzeug mit dieser ID unter den vordefinierten Fahrzeugen oder den Fahrzeugen Ihrer Organisation. | Prüfen Sie die ID anhand von GET /v1/vehicles. | Nein |
| 404 | template_not_found | Keine Vorlage mit dieser ID in Ihrer Organisation. | Prüfen Sie die ID anhand von GET /v1/templates. | Nein |
| 404 | project_not_found | Kein Projekt mit dieser ID in Ihrer Organisation. | Prüfen Sie die ID anhand von GET /v1/projects. | Nein |
| 409 | job_not_finished | Der Job wartet noch oder läuft. | Fragen Sie GET /v1/jobs/{id} ab, bis status den Wert succeeded hat. | Ja |
| 409 | project_busy | Das Projekt wird gerade berechnet (in der App oder von einem anderen Job). | Warten Sie, bis dieser Lauf beendet ist, und versuchen Sie es dann erneut. | Ja |
| 409 | job_failed | Der Job ist fehlgeschlagen; es gibt kein Ergebnis. | Lesen Sie job.error; Fehler auf unserer Seite kosten nichts (time_limit_exceeded wird wie ein abgebrochener Job berechnet). Senden Sie den Job erneut, wenn die Ursache vorübergehend war. | Nein |
| 409 | job_canceled | Der Job wurde abgebrochen; es gibt kein Ergebnis. | Senden Sie ihn bei Bedarf erneut. | Nein |
| 409 | job_already_finished | Der Job ist bereits beendet und kann nicht abgebrochen werden. | Nichts zu tun. | Nein |
| 400 | idempotency_key_invalid | Der Header Idempotency-Key ist länger als 128 Zeichen. | Verwenden Sie einen kürzeren Schlüssel (eine UUID genügt). | Nein |
| 410 | result_expired | Die Aufbewahrungsfrist des Ergebnisses ist abgelaufen; es wurde gelöscht. | Senden Sie den Job erneut, wenn Sie den Plan noch einmal brauchen. | Nein |
| 413 | payload_too_large | Der Anfrage-Body ist größer als 10 MB. | Senden Sie weniger oder einfachere Artikel. | Nein |
| 422 | validation_failed | Die Anfrage ist wohlgeformtes JSON, beschreibt aber einen ungültigen Job. details[] listet alle Probleme auf. | Korrigieren Sie jedes in details[].path genannte Feld; Validierungsfehler sind kostenlos. | Nein |
| 429 | rate_limited | Zu viele Anfragen in der aktuellen Minute, Stunde oder am aktuellen Tag (pro Schlüssel oder pro Organisation) oder mehr als 60 fehlgeschlagene Authentifizierungen pro Minute von Ihrer IP-Adresse. | Warten Sie die in Retry-After angegebenen Sekunden ab und versuchen Sie es dann mit Backoff erneut. | Ja |
| 429 | too_many_jobs | Die Organisation hat bereits die maximale Zahl wartender und laufender Jobs. | Warten Sie, bis laufende Jobs beendet sind, und versuchen Sie es dann erneut. | Ja |
| 500 | internal_error | Auf unserer Seite ist ein Fehler aufgetreten. | Wiederholen Sie die Anfrage mit Backoff; nennen Sie dem Support die request_id, wenn der Fehler bestehen bleibt. | Ja |
| 503 | api_disabled | Die API ist vorübergehend deaktiviert (Wartung) oder für die Organisation abgeschaltet. | Versuchen Sie es später erneut. | Ja |
Validierungsdetails
details[].code bei 422 validation_failed:
| Code | Bedeutung |
|---|---|
required | Ein Pflichtfeld fehlt |
invalid_value | Falscher Typ oder kein zulässiger Wert |
out_of_range | Zu klein, zu groß oder zu lang |
duplicate_id | Eine ID wird doppelt verwendet |
unknown_vehicle | Kein vordefiniertes oder eigenes Fahrzeug mit dieser vehicle_id |
unknown_template | Keine eigene Vorlage mit dieser template_id |
type_not_allowed | Fahrzeugtyp ist für Ihre Organisation nicht freigeschaltet |
unknown_group | Ein Artikel nennt eine Gruppe, die nicht aufgeführt ist |
does_not_fit | Der Artikel passt in keines der angegebenen Fahrzeuge |
too_many_items | Mehr Artikeleinheiten als das Job-Limit erlaubt |
too_many_vehicles | Mehr Fahrzeuge als das Job-Limit erlaubt |
unknown_field | Ein Feld, das die API nicht kennt |
Job-Fehler
Ein Job mit failed oder canceled nennt den Grund in job.error.code:
| Code | Bedeutung |
|---|---|
canceled | Abgebrochen über DELETE /v1/jobs/{id}. Berechnet werden Jobgebühr + genutzte Rechenzeit. |
time_limit_exceeded | Das Rechenzeitbudget war aufgebraucht, bevor ein Fahrzeug beladen wurde. Wird wie ein abgebrochener Job berechnet: Jobgebühr, Zuschlag für große Ladungen und genutzte Rechenzeit, nie die Fahrzeuggebühr. |
engine_failed | Der Ladealgorithmus ist fehlgeschlagen. Keine Kosten. |
queue_timeout | Der Job hat zu lange auf freie Rechenkapazität gewartet. Keine Kosten. |
server_restarted | Der Dienst wurde neu gestartet, während der Job wartete oder lief. Keine Kosten. |
Wiederholungen
Wiederholen Sie Anfragen nach 429, 500 und 503 mit exponentiellem Backoff und beachten Sie Retry-After. Senden Sie denselben Idempotency-Key mit (Idempotenz). Wiederholen Sie andere 4xx-Antworten nie unverändert.