Errori
L’envelope dell’errore
Ogni risposta non 2xx ha la stessa forma. Ramifica su error.code, mai sul messaggio. error.details dipende dal codice; per i rifiuti di una chiave API contiene un motivo (reason).
Il requestId è anche nell’header X-Request-Id di ogni risposta, riuscita o no. Citalo quando contatti l’assistenza.
403 Forbidden
{ "error": { "code": "forbidden", "message": "This key is missing the codes:write scope", "details": { "reason": "missing_scope", "scope": "codes:write" }, "requestId": "req_7Hq2mK9xT4" }}Codici di errore
400validation_failedIl corpo o la query non ha superato la validazione. details è un elenco di problemi { path, message }.400bad_requestLa richiesta è ben formata ma non può essere eseguita; details.reason ne spiega il motivo.401unauthorizedLa chiave manca, è malformata, revocata o scaduta.403forbiddenLa chiave non può farlo: manca uno scope, c’è una restrizione di cartella o IP, oppure la rotta è solo per l’app. Vedi details.reason.404not_foundNessun oggetto di questo tipo in questo spazio di lavoro, oppure la chiave non può vederlo.409conflictUno slug o un hostname è già in uso, oppure una richiesta con la stessa Idempotency-Key è ancora in corso.422idempotency_conflictL’Idempotency-Key è già stata usata con un corpo diverso.410goneL’oggetto esisteva ed è stato eliminato o rilasciato.413payload_too_largeIl corpo o il caricamento supera il limite di dimensione.429rate_limitedSuperato il budget al minuto o di burst dello spazio di lavoro. Attendi Retry-After secondi.403plan_limit_reachedRaggiunto un limite del piano (codici, righe in blocco, job…). details indica il limite e l’utilizzo.403feature_not_in_planIl piano dello spazio di lavoro non lo include (ad esempio i webhook su Free).422unsafe_destinationLa destinazione non ha superato il controllo di Google Web Risk e delle blocklist.500internalQualcosa è andato storto da parte nostra. Riprova con backoff; se persiste, indica il requestId.503unavailableTemporaneamente non disponibile. Riprova con backoff.Rifiuti delle chiavi API
details.reason dei rifiuti specifici delle chiavi API.
403 forbiddenmissing_scopeLa chiave non ha lo scope della rotta (details.scope), oppure il ruolo di chi l’ha creata non lo consente più.403 forbiddensession_requiredLa rotta è solo per l’app (fatturazione, membri, gestione delle chiavi…); le chiavi non possono chiamarla.403 forbiddenapi_key_folder_restrictedLa chiave è limitata ad alcune cartelle (details.folderIds) e la richiesta ne riguarda un’altra.403 forbiddenip_not_allowedL’indirizzo di chi chiama è fuori dalla allowlist IP della chiave.400 bad_requesttest_mode_unavailableLe chiavi sk_test_ non si possono creare: non esiste ancora una modalità di test. Usa uno spazio di lavoro separato per i test.400 bad_requesttoo_many_api_keysLo spazio di lavoro ha già 50 chiavi attive (details.limit). Revocane prima una.403 forbiddenscope_not_grantableIl tuo ruolo non può concedere questi scope (details.scopes), ad esempio webhooks:write come editor.Cosa ritentare
Ritenta 429 dopo Retry-After secondi, e 500 o 503 con backoff esponenziale. Ogni altro 4xx richiede prima una modifica alla richiesta. Le richieste POST si possono ritentare senza rischi quando invii lo stesso Idempotency-Key.