/v1 é application/problem+json (RFC 9457) com um conjunto fixo de campos:
code como critério de ramificação, nunca detail — code é um contrato estável legível por máquina; detail é legível por pessoas 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 alteração do 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; não comprova que uma gravação não teve efeito. Repita as leituras com um limite finito de tentativas e de tempo, com backoff exponencial e jitter. Respeite Retry-After quando presente, inclusive em um 409 ou 429 passível de nova tentativa.
Para mutações, siga o contrato de idempotência e recuperação documentado da operação. Preserve a chave original e a requisição original quando houver suporte. Não gere uma nova chave após um timeout ou 5xx: isso pode repetir uma gravação que já foi concluída com êxito. Um cabeçalho Idempotency-Key não oferece nenhuma proteção em uma operação que não o suporte.