/v1 é application/problem+json (RFC 9457) com um conjunto fixo de campos:
code, nunca em detail — code é um contrato estável legível por máquina; detail é legível por humanos e pode mudar. param está presente quando o erro é atribuível a um parâmetro específico da requisição. Inclua request_id ao entrar em contato com o suporte.
Códigos de erro
O conjunto de códigos é fechado: novos códigos representam uma mudança no contrato público e são anunciados por meio do changelog da API. Uma resposta
retryable: true significa que a condição pode ser resolvida; isso não comprova que uma gravação não teve efeito. Repita as leituras com um limite finito de tentativas e de tempo, backoff exponencial e jitter. Respeite Retry-After quando presente, inclusive em um 409 ou 429 que permita nova tentativa.
Para mutações, siga o contrato de idempotência e recuperação documentado da operação. Preserve a chave e a requisição originais quando houver suporte. Não crie uma nova chave após um timeout ou 5xx: isso pode repetir uma gravação bem-sucedida. Um cabeçalho Idempotency-Key não oferece nenhuma proteção em uma operação que não o suporte.