Fehler
Der Fehler-Umschlag
Jede Antwort außerhalb von 2xx hat dieselbe Form. Verzweigen Sie nach error.code, nie nach der Meldung. error.details hängt vom Code ab; bei Ablehnungen eines API-Schlüssels enthält es einen reason.
Die requestId steht auch im Header X-Request-Id jeder Antwort, ob erfolgreich oder nicht. Nennen Sie sie, wenn Sie den Support kontaktieren.
403 Forbidden
{ "error": { "code": "forbidden", "message": "This key is missing the codes:write scope", "details": { "reason": "missing_scope", "scope": "codes:write" }, "requestId": "req_7Hq2mK9xT4" }}Fehlercodes
400validation_failedBody oder Query haben die Validierung nicht bestanden. details ist eine Liste von { path, message }-Problemen.400bad_requestDie Anfrage ist wohlgeformt, lässt sich aber nicht ausführen; details.reason sagt warum.401unauthorizedDer Schlüssel fehlt, ist fehlerhaft, widerrufen oder abgelaufen.403forbiddenDer Schlüssel darf das nicht: ein fehlender Scope, eine Ordner- oder IP-Beschränkung oder eine Route nur für die App. Siehe details.reason.404not_foundKein solches Objekt in diesem Arbeitsbereich, oder der Schlüssel kann es nicht sehen.409conflictEin Slug oder Hostname ist vergeben, oder eine Anfrage mit demselben Idempotency-Key läuft noch.422idempotency_conflictDer Idempotency-Key wurde zuvor mit einem anderen Body verwendet.410goneDas Objekt existierte und wurde gelöscht oder freigegeben.413payload_too_largeBody oder Upload überschreiten das Größenlimit.429rate_limitedDas Budget des Arbeitsbereichs pro Minute oder für Spitzen ist überschritten. Warten Sie Retry-After Sekunden.403plan_limit_reachedEin Tariflimit (Codes, Massenzeilen, Jobs…) ist erreicht. details nennt das Limit und die Nutzung.403feature_not_in_planDer Tarif des Arbeitsbereichs enthält das nicht (zum Beispiel Webhooks im Free-Tarif).422unsafe_destinationDas Ziel hat die Prüfung gegen Google Web Risk und die Sperrliste nicht bestanden.500internalAuf unserer Seite ist etwas fehlgeschlagen. Versuchen Sie es mit Backoff erneut; nennen Sie dem Support die requestId, wenn der Fehler bestehen bleibt.503unavailableVorübergehend nicht verfügbar. Versuchen Sie es mit Backoff erneut.Ablehnungen von API-Schlüsseln
details.reason der Ablehnungen, die speziell für API-Schlüssel gelten.
403 forbiddenmissing_scopeDem Schlüssel fehlt der Scope der Route (details.scope), oder die Rolle seines Erstellers erlaubt es nicht mehr.403 forbiddensession_requiredDie Route gilt nur für die App (Abrechnung, Mitglieder, Schlüsselverwaltung…); Schlüssel können sie nicht aufrufen.403 forbiddenapi_key_folder_restrictedDer Schlüssel ist auf einige Ordner beschränkt (details.folderIds), und die Anfrage zielt auf einen anderen.403 forbiddenip_not_allowedDie Adresse des Aufrufers liegt außerhalb der IP-Allowlist des Schlüssels.400 bad_requesttest_mode_unavailablesk_test_-Schlüssel können nicht erstellt werden: Es gibt noch keinen Testmodus. Nutzen Sie für Tests einen separaten Arbeitsbereich.400 bad_requesttoo_many_api_keysDer Arbeitsbereich hat bereits 50 aktive Schlüssel (details.limit). Widerrufen Sie zuerst einen.403 forbiddenscope_not_grantableIhre Rolle kann diese Scopes nicht vergeben (details.scopes), z. B. webhooks:write als Editor.Was erneut zu versuchen ist
Wiederholen Sie 429 nach Retry-After Sekunden und 500 oder 503 mit exponentiellem Backoff. Jedes andere 4xx braucht zuerst eine Änderung an der Anfrage. POST-Anfragen lassen sich gefahrlos wiederholen, wenn Sie denselben Idempotency-Key senden.