Fouten
De foutenvelop
Elk niet-2xx-antwoord heeft dezelfde vorm. Vertak op error.code, nooit op het bericht. error.details hangt van de code af; bij weigeringen van een API-sleutel bevat het een reden (reason).
Het requestId staat ook in de X-Request-Id-header van elk antwoord, geslaagd of niet. Noem het als je contact opneemt met support.
403 Forbidden
{ "error": { "code": "forbidden", "message": "This key is missing the codes:write scope", "details": { "reason": "missing_scope", "scope": "codes:write" }, "requestId": "req_7Hq2mK9xT4" }}Foutcodes
400validation_failedDe body of query is niet gevalideerd. details is een lijst met { path, message }-problemen.400bad_requestHet verzoek is correct opgebouwd maar kan niet worden uitgevoerd; details.reason zegt waarom.401unauthorizedDe sleutel ontbreekt, is onjuist opgebouwd, ingetrokken of verlopen.403forbiddenDe sleutel mag dit niet: een ontbrekende scope, een map- of IP-beperking, of een route alleen voor de app. Zie details.reason.404not_foundZo’n object bestaat niet in deze werkruimte, of de sleutel kan het niet zien.409conflictEen slug of hostnaam is al in gebruik, of een verzoek met dezelfde Idempotency-Key loopt nog.422idempotency_conflictDe Idempotency-Key is eerder gebruikt met een andere body.410goneHet object bestond en is verwijderd of vrijgegeven.413payload_too_largeDe body of upload is groter dan de limiet.429rate_limitedBoven het budget per minuut of burst van de werkruimte. Wacht Retry-After seconden.403plan_limit_reachedEen abonnementslimiet (codes, bulkrijen, jobs…) is bereikt. details noemt de limiet en het gebruik.403feature_not_in_planHet abonnement van de werkruimte bevat dit niet (bijvoorbeeld webhooks op Free).422unsafe_destinationDe bestemming is afgekeurd door de Google Web Risk- en blocklistcontrole.500internalEr ging iets mis aan onze kant. Probeer opnieuw met backoff; noem de requestId als het blijft duren.503unavailableTijdelijk niet beschikbaar. Probeer opnieuw met backoff.Weigeringen van API-sleutels
details.reason van de weigeringen die specifiek zijn voor API-sleutels.
403 forbiddenmissing_scopeDe sleutel mist de scope van de route (details.scope), of de rol van de maker staat het niet meer toe.403 forbiddensession_requiredDe route is alleen voor de app (facturering, leden, sleutelbeheer…); sleutels kunnen hem niet aanroepen.403 forbiddenapi_key_folder_restrictedDe sleutel is beperkt tot bepaalde mappen (details.folderIds) en het verzoek betreft een andere.403 forbiddenip_not_allowedHet adres van de aanroeper valt buiten de IP-allowlist van de sleutel.400 bad_requesttest_mode_unavailablesk_test_-sleutels kunnen niet worden aangemaakt: er is nog geen testmodus. Gebruik een aparte werkruimte om te testen.400 bad_requesttoo_many_api_keysDe werkruimte heeft al 50 actieve sleutels (details.limit). Trek er eerst een in.403 forbiddenscope_not_grantableJe rol kan deze scopes niet toekennen (details.scopes), bijvoorbeeld webhooks:write als editor.Wat opnieuw proberen
Probeer 429 opnieuw na Retry-After seconden, en 500 of 503 met exponentiële backoff. Elke andere 4xx vraagt eerst een wijziging van het verzoek. POST-verzoeken zijn veilig opnieuw te proberen als je dezelfde Idempotency-Key meestuurt.