Erros
O envelope do erro
Toda resposta que não seja 2xx tem o mesmo formato. Ramifique em error.code, nunca na mensagem. error.details depende do código; nas recusas de uma chave de API, traz um motivo (reason).
O requestId também está no cabeçalho X-Request-Id de toda resposta, bem-sucedida ou não. Informe-o ao falar com o suporte.
403 Forbidden
{ "error": { "code": "forbidden", "message": "This key is missing the codes:write scope", "details": { "reason": "missing_scope", "scope": "codes:write" }, "requestId": "req_7Hq2mK9xT4" }}Códigos de erro
400validation_failedO corpo ou a consulta falhou na validação. details é uma lista de problemas { path, message }.400bad_requestA requisição está bem formada, mas não pode ser feita; details.reason diz por quê.401unauthorizedA chave está ausente, malformada, revogada ou expirada.403forbiddenA chave não pode fazer isso: falta um escopo, há uma restrição de pasta ou de IP, ou a rota é só do app. Veja details.reason.404not_foundNão existe esse objeto neste espaço de trabalho, ou a chave não consegue vê-lo.409conflictUm slug ou hostname já está em uso, ou uma requisição com a mesma Idempotency-Key ainda está em andamento.422idempotency_conflictA Idempotency-Key já foi usada com outro corpo.410goneO objeto existia e foi excluído ou liberado.413payload_too_largeO corpo ou o upload passa do limite de tamanho.429rate_limitedPassou do orçamento por minuto ou de burst do espaço de trabalho. Espere Retry-After segundos.403plan_limit_reachedUm limite do plano (códigos, linhas em massa, jobs…) foi atingido. details informa o limite e o uso.403feature_not_in_planO plano do espaço de trabalho não inclui isso (por exemplo, webhooks no Free).422unsafe_destinationO destino não passou na verificação do Google Web Risk e das listas de bloqueio.500internalAlgo falhou do nosso lado. Tente de novo com backoff; informe o requestId se persistir.503unavailableTemporariamente indisponível. Tente de novo com backoff.Recusas de chaves de API
details.reason das recusas específicas das chaves de API.
403 forbiddenmissing_scopeA chave não tem o escopo da rota (details.scope), ou o papel de quem a criou não permite mais.403 forbiddensession_requiredA rota é só do app (cobrança, membros, gerenciamento de chaves…); as chaves não podem chamá-la.403 forbiddenapi_key_folder_restrictedA chave é limitada a algumas pastas (details.folderIds) e a requisição mira outra.403 forbiddenip_not_allowedO endereço de quem chama está fora da allowlist de IPs da chave.400 bad_requesttest_mode_unavailableChaves sk_test_ não podem ser criadas: ainda não existe modo de teste. Use um espaço de trabalho separado para testes.400 bad_requesttoo_many_api_keysO espaço de trabalho já tem 50 chaves ativas (details.limit). Revogue uma primeiro.403 forbiddenscope_not_grantableSeu papel não pode conceder estes escopos (details.scopes), por exemplo webhooks:write como editor.O que tentar de novo
Tente 429 de novo depois de Retry-After segundos, e 500 ou 503 com backoff exponencial. Qualquer outro 4xx exige antes uma mudança na requisição. As requisições POST podem ser repetidas com segurança quando você envia o mesmo Idempotency-Key.