Entwickler

Fehler der Public API

Den einen Fehler-Body lesen, mit dem jede Operation der Costfluent Public API antwortet, und an seinem Code entscheiden, ob ein erneuter Versuch sinnvoll ist.

Jeder Fehler, vom abgelehnten Token bis zur fehlgeschlagenen Validierung, antwortet mit demselben Body: RFC-7807-Problem-Details, gesendet als application/problem+json, mit einem maschinenlesbaren code und der Angabe, ob ein erneuter Versuch gelingen kann.


Code
{
  "type": "about:blank",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "retryable": false,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "name": "amount", "reason": "\"1.123456789\" is not a decimal amount with at most 8 decimal places." }
  ]
}

Die Felder

Feld	Bedeutung
`status`	Der HTTP-Status, im Body wiederholt.
`code`	Was schiefging, in Snake Case, etwa `not_found` oder `validation_failed`. Er bleibt über Releases gleich; verzweige danach, nie nach dem Text.
`retryable`	Ob dieselbe Anfrage später gelingen kann.
`title`, `detail`	Eine Zusammenfassung und, wenn vorhanden, die Einzelheiten, für Menschen zum Lesen. Der Wortlaut kann sich ändern.
`traceId`	Der Trace der Anfrage. Nenne ihn, wenn du den Support kontaktierst.
`errors`	Die einzelnen Fehler: ein Eintrag je ungültigem Feld, mit `name` und `reason`, oder ein allgemeiner Eintrag.

Statuscodes

Status	Wann
`400`	Die Anfrage ist fehlerhaft oder ein Feld ungültig; `errors` nennt jedes Feld.
`401`	Das Token fehlt, ist ungültig, abgelaufen oder widerrufen.
`403`	Dem Token fehlt die Berechtigung der Operation, oder ein Workspace-Token nennt einen anderen Workspace; siehe Authentifizierung.
`404`	Das Objekt existiert nicht oder ist für dieses Token nicht sichtbar.
`409`	Die Anfrage widerspricht dem aktuellen Zustand des Objekts oder einer gleichzeitigen Änderung. Eine Löschung, die abgelehnt wird, weil etwas das Objekt noch verwendet, etwa ein Budget, das einen Kostenbericht misst, antwortet mit `in_use`, und `errors` nennt, was es verwendet.
`412`	Ein `If-Match` nennt eine Version, die das Objekt nicht mehr hat; lies es erneut und versuche es noch einmal. Siehe Datenformate.
`422`	Eine Geschäftsregel lehnt die Anfrage ab, etwa ein Limit deines Plans.
`429`	Zu viele Anfragen; siehe Rate Limits.
`500`	Ein unerwarteter Fehler. Nenne die `traceId`.
`503`	Eine Abhängigkeit ist kurz nicht verfügbar; versuche es nach `Retry-After` erneut.

Wie es sich verhält

retryable ist true für rate_limit_exceeded, provider_unavailable und external_timeout. Wiederhole diese mit Verzögerung; alles andere zu wiederholen ergibt dieselbe Antwort.
Ein 400 wegen eines Anfrage-Bodys, der kein gültiges JSON ist, oder eines Felds vom falschen Typ, hat dieselbe Form wie eines wegen einer verletzten Regel.

Verwandte Seiten

Paginierung der Public API Rate Limits der Public API

Code

{
  "type": "about:blank",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "retryable": false,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "name": "amount", "reason": "\"1.123456789\" is not a decimal amount with at most 8 decimal places." }
  ]
}

Die Felder

Feld

Bedeutung

status

Der HTTP-Status, im Body wiederholt.

code

Was schiefging, in Snake Case, etwa not_found oder validation_failed. Er bleibt über Releases gleich; verzweige danach, nie nach dem Text.

retryable

Ob dieselbe Anfrage später gelingen kann.

title, detail

Eine Zusammenfassung und, wenn vorhanden, die Einzelheiten, für Menschen zum Lesen. Der Wortlaut kann sich ändern.

traceId

Der Trace der Anfrage. Nenne ihn, wenn du den Support kontaktierst.

errors

Die einzelnen Fehler: ein Eintrag je ungültigem Feld, mit name und reason, oder ein allgemeiner Eintrag.

Statuscodes

Status

Wann

400

Die Anfrage ist fehlerhaft oder ein Feld ungültig; errors nennt jedes Feld.

401

Das Token fehlt, ist ungültig, abgelaufen oder widerrufen.

403

Dem Token fehlt die Berechtigung der Operation, oder ein Workspace-Token nennt einen anderen Workspace; siehe Authentifizierung.

404

Das Objekt existiert nicht oder ist für dieses Token nicht sichtbar.

409

Die Anfrage widerspricht dem aktuellen Zustand des Objekts oder einer gleichzeitigen Änderung. Eine Löschung, die abgelehnt wird, weil etwas das Objekt noch verwendet, etwa ein Budget, das einen Kostenbericht misst, antwortet mit in_use, und errors nennt, was es verwendet.

412

Ein If-Match nennt eine Version, die das Objekt nicht mehr hat; lies es erneut und versuche es noch einmal. Siehe Datenformate.

422

Eine Geschäftsregel lehnt die Anfrage ab, etwa ein Limit deines Plans.

429

Zu viele Anfragen; siehe Rate Limits.

500

Ein unerwarteter Fehler. Nenne die traceId.

503

Eine Abhängigkeit ist kurz nicht verfügbar; versuche es nach Retry-After erneut.

Wie es sich verhält

retryable ist true für rate_limit_exceeded, provider_unavailable und external_timeout. Wiederhole diese mit Verzögerung; alles andere zu wiederholen ergibt dieselbe Antwort.

Ein 400 wegen eines Anfrage-Bodys, der kein gültiges JSON ist, oder eines Felds vom falschen Typ, hat dieselbe Form wie eines wegen einer verletzten Regel.