---
title: Erros e repetição
description: Códigos estáveis e decisões de recuperação da API administrativa.
---
Uma falha JSON tem `error.code`, `message`, `requestId` e `documentationUrl`. Alguns erros incluem `details` ou metadados do recurso. Use o código e o status HTTP para decidir; a mensagem pode evoluir. O cabeçalho `X-Request-Id` permite correlacionar diagnóstico sem registrar a credencial.

| HTTP | Código | Ação |
| --- | --- | --- |
| 400 | `invalid_request`, `invalid_cursor` | Corrigir cabeçalhos/query/JSON; cursor exige o contexto original e vale por 15 min |
| 401 | `unauthenticated` | Conferir validade, revogação e ambiente da credencial |
| 403 | `insufficient_permission` | Conferir permissão e tipo de credencial; somente o proprietário pode ampliar o acesso |
| 404 | `not_found` | Conferir recurso e aplicativo; este status também protege recursos fora do escopo |
| 409 | `resource_conflict`, `idempotency_conflict`, `operation_in_progress` | Conferir dependências/identidade; não trocar payload sob a mesma chave |
| 409 | `secret_not_replayable` | Emissão confirmada; segredo não pode ser recuperado; consultar os metadados |
| 412 | `revision_conflict` | Consultar o recurso novamente e decidir a alteração sobre a revisão atual |
| 413 | `payload_too_large` | Reduzir tamanho; JSON 32 KiB, imagem 1 MiB e overhead multipart 64 KiB |
| 415 | `unsupported_media_type` | Usar JSON ou multipart, conforme o endpoint |
| 422 | `validation_failed` | Corrigir campos e semântica da operação |
| 428 | `precondition_required` | Enviar If-Match com ETag forte atual |
| 429 | `rate_limited` | Aguardar Retry-After; trocar de chave não reinicia quotas compartilhadas |
| 500, 503 | `internal_error`, `dependency_unavailable` | Consultar diagnóstico; em mutação incerta repetir a mesma intenção |

## Revision conflict

`If-Match` usa a revisão retornada entre aspas. Omissão retorna 428; revisão antiga retorna 412. Uma nova intenção exige nova chave; repetir a mesma intenção exige chave, corpo e precondição originais.

## Secret not replayable

O segredo de chave de API aparece apenas na resposta inicial. Um replay confirmado devolve metadados com 409, sem emitir outro segredo. Consulte a credencial e, se necessário, faça rotação autorizada.

## Dependency unavailable

Timeout não prova que uma mutação falhou antes do efeito. Use a mesma idempotência por até 24h. Upload/remoção de arquivo têm intenção durável para reconciliar SQL e R2. Consulte estado antes de iniciar outra intenção. A [referência](/referencia/) inclui exemplos completos de respostas de erro por operação.