Erros e repetição

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 inclui exemplos completos de respostas de erro por operação.