Erros

Quando algo dá errado, a API responde com um código HTTP (4xx para erro seu, 5xx para erro da plataforma) e um corpo JSON com a descrição. O código HTTP é o que decide o seu fluxo (repetir, corrigir, parar); a mensagem serve para o log e para a pessoa que vai investigar.

O formato do erro

{ "error": "order not found" }

O campo error é a mensagem curta (ou um código em snake_case, como account_locked). Dependendo da rota, vêm campos extras:

Códigos HTTP

Exemplos reais

Falta a credencial (401)

{ "error": "missing authorization header" }

Sem permissão (403)

{ "error": "insufficient privileges", "required": "manage_orders" }

Registro inexistente (404)

{ "error": "order not found" }

Validação (400)

{ "error": "validation_failed", "fields": { "category_id": "category_required", "name": "name_required" } }

{ "error": "at least one item is required" }

Conflito de dados (500 em alguns casos)

Algumas regras de unicidade ainda respondem 500 em vez de 409. Um exemplo é o CPF de um cliente que já pertence a outra conta:

{ "error": "failed to create user", "detail": "CPF already registered by another user" }

Leia o detail quando um 500 vier de uma escrita; ele costuma dizer o que há de errado nos seus dados.

Limite de requisições (429)

{ "error": "rate limit exceeded", "detail": "too many requests, please try again later" }

Tempo esgotado (503)

{ "error": "request timeout", "code": "handler_timeout" }

Erros que acontecem antes da sua rota

Três verificações rodam antes do código da operação, e por isso os erros delas se parecem em toda a API:

1. A loja (Endereço e ambientes): 404 tenant not found, 503 tenant_suspended.
2. O limite de requisições (429 rate limit exceeded).
3. A autenticação (Autenticação): 401 e 403 com as mensagens da tabela daquela página.

Mensagens em português

Alguns textos de detail e de regras da loja vêm em português, porque nascem de validações escritas em português (por exemplo, o aviso de uma data inválida em um filtro). Eles são devolvidos como o servidor os escreve e podem mudar. Não faça comparação de texto com eles.

Como tratar erros no seu código

1. Olhe o código HTTP primeiro

   2xx segue em frente. 401 tenta renovar o token uma vez. 429, 503 e 5xx entram em repetição com espera. O resto é erro seu.

2. Leia o corpo para o log e para o usuário

   Registre o corpo inteiro e o X-Request-Id. Use error e, em validações, fields.

3. Repita só o que é seguro repetir

   Nunca repita um 400, 403 ou 404 sem mudar algo. Para criações (pedido), use o idempotency_key para que uma repetição não duplique o registro (Limites e boas práticas).

Erros comuns

• Ignorar os campos extras. fields, code e required dizem exatamente o que corrigir.
• Repetir um 400 em loop. Ele nunca passa sem mudança.
• Fazer if mensagem == "...". Use o código HTTP e, quando existir, o campo code.
• Ignorar o 500 com detail. Em escritas, ele costuma apontar um dado duplicado ou inválido.

Veja também