Fehler

Fehler verwenden HTTP-Statuscodes und einen JSON-Body mit einem stabilen, maschinenlesbaren code, einer Meldung für Menschen und der ID der Anfrage.

402 application/json

{
  "error": {
    "code": "quota_exceeded",
    "message": "This organisation has used all 1,000 marks of this month on its plan. Upgrade the plan for more, or wait for the 1st of next month (UTC).",
    "request_id": "req_7Hc2kQm0Zt1L"
  }
}

Verzweigen Sie anhand von code, nie anhand von message: Codes gehören zu API v1 und ändern sich nicht; Meldungen können klarer werden. Jede Antwort, ob erfolgreich oder nicht, trägt dieselbe ID in ihrem Header X-Request-Id. Nennen Sie sie, wenn Sie uns schreiben.

Codes

Fehlercodes
Status	Code	Bedeutung	Was zu tun ist
400	`invalid_request`	Die Anfrage ist fehlerhaft, oder ein Feld liegt außerhalb des zulässigen Bereichs.	Korrigieren Sie die Anfrage; die Meldung nennt das Feld.
400	`unknown_field`	Ein Feld, das der Endpunkt nicht kennt.	Prüfen Sie die Schreibweise des Felds anhand der Referenz.
400	`option_not_available`	Eine geplante Option, die noch nicht verfügbar ist.	Lassen Sie sie vorerst weg; das Änderungsprotokoll sagt, wann sie kommt.
401	`missing_api_key`	Kein Bearer-Schlüssel im Authorization-Header.	Senden Sie Authorization: Bearer sk_….
401	`invalid_api_key`	Der Schlüssel stammt nicht von uns.	Prüfen Sie den Schlüssel; erstellen Sie einen neuen, falls er verloren ist.
401	`api_key_revoked`	Der Schlüssel wurde widerrufen oder sein Projekt gelöscht.	Verwenden Sie einen anderen Schlüssel.
402	`quota_exceeded`	Das Kontingent des Monats ist aufgebraucht.	Warten Sie bis zum Ersten des Monats (UTC), oder machen Sie ein Upgrade.
403	`insufficient_scope`	Dem Schlüssel fehlt die Berechtigung dieses Endpunkts.	Verwenden Sie einen Schlüssel mit dieser Berechtigung, oder erstellen Sie einen.
403	`ip_not_allowed`	Die Adresse steht nicht auf der IP-Allowlist des Schlüssels.	Rufen Sie von einer erlaubten Adresse aus auf, oder passen Sie die Allowlist an.
403	`key_not_allowed_in_url`	Ein Schlüssel mit Berechtigungen über tsa hinaus wurde in einer URL gesendet.	Verwenden Sie einen Schlüssel, der nur tsa hat, und rotieren Sie den gesendeten.
404	`not_found`	Unter diesem Pfad gibt es keinen Endpunkt.	Prüfen Sie den Pfad und die API-Version.
404	`upload_not_found`	Der in „upload“ genannte Upload ist keiner, den dieser Schlüssel verwenden kann: unbekannt, bereits verwendet, älter als eine Stunde oder von einem anderen Schlüssel erstellt.	Erstellen Sie mit diesem Schlüssel einen neuen Upload (POST /v1/uploads).
405	`method_not_allowed`	Der Endpunkt akzeptiert diese Methode nicht.	Siehe den Header Allow.
413	`payload_too_large`	Der Body überschreitet das Limit des Endpunkts.	4 MB pro Anfrage: Senden Sie größere Dateien (bis 25 MB) über POST /v1/uploads. 4 KB für Zeitstempelanfragen.
415	`unsupported_media_type`	Die Datei oder der Content-Type der Anfrage wird nicht akzeptiert.	Senden Sie PNG, JPEG oder WebP als multipart/form-data.
422	`content_blocked`	POST /v1/mark: Die Sicherheitsprüfung hat das Bild blockiert; es wurde nichts markiert. „safety“ im Body nennt den Grund.	Senden Sie dasselbe Bild nicht erneut. Die durchgeführten Prüfungen zählen, die Markierung nicht.
429	`rate_limited`	Zu viele Aufrufe in dieser Minute für diesen Schlüssel.	Warten Sie Retry-After Sekunden, und versuchen Sie es dann erneut.
500	`internal_error`	Bei uns ist etwas fehlgeschlagen.	Versuchen Sie es mit Backoff erneut; es wurde nichts berechnet.
502	`mark_failed`	Die Datei ließ sich nicht markieren und verifizieren; es wurde keine Datei zurückgegeben.	Versuchen Sie es einmal erneut; bleibt der Fehler bestehen, wenden Sie sich mit der ID der Anfrage an den Support.
503	`marker_unavailable`	Der Markierungsdienst ist kurzzeitig nicht verfügbar.	Versuchen Sie es mit Backoff erneut; es wurde nichts berechnet.
503	`tsa_unavailable`	Der Zeitstempelserver ist kurzzeitig nicht verfügbar.	Versuchen Sie es mit Backoff erneut; es wurde nichts berechnet.
503	`storage_unavailable`	Uploads sind kurzzeitig nicht verfügbar.	Versuchen Sie es mit Backoff erneut; es wurde nichts berechnet, und der Upload bleibt erhalten.

Erneute Versuche

429: Warten Sie so viele Sekunden, wie Retry-After angibt.
500, 502, 503: Versuchen Sie es mit exponentiellem Backoff erneut (1 s, 2 s, 4 s …), bis zu einigen Malen. Fehlgeschlagene Aufrufe werden nie auf Ihr Kontingent angerechnet.
Andere 4xx: Nicht unverändert wiederholen; korrigieren Sie zuerst die Anfrage.