Erros

Quando uma chamada falha, o código de status HTTP diz a categoria do problema e o corpo JSON diz o motivo. A API tem um formato de corpo principal, mas algumas rotas e camadas usam outro. Escreva seu tratamento de erro olhando primeiro o status e só depois o corpo.

Formatos de corpo

Formato simples (o mais comum)

{ "error": "product not found" }

Com detalhe adicional, quando há:

{
  "error": "invalid request body",
  "detail": "invalid character 'b' looking for beginning of object key string"
}

error é a mensagem curta; detail explica a causa. Textos vindos do banco de dados são sempre trocados por uma frase genérica, nunca expõem nomes internos.

Validação por campo

Quando o corpo da requisição é rejeitado por regras de formulário, a resposta traz um código por campo:

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

Cada valor de fields é um código curto e estável (required, name_required...) que você pode mapear para a sua própria mensagem. O status é normalmente 400; algumas rotas usam 422 com o mesmo formato.

Formato com objeto

Algumas rotas devolvem o erro dentro de um objeto:

{
  "error": {
    "code": "not_found",
    "message": "vendor not found",
    "details": null
  }
}

Se error for um objeto, leia error.code e error.message. Se for uma string, é o formato simples. Teste o tipo antes de ler.

Códigos de status

Erros de autenticação e permissão, por ordem

Uma chamada protegida é verificada nesta ordem, e o primeiro problema encontrado é o devolvido.

1. Loja (404 tenant not found, 503 de loja). Veja Lojas e resolução de host.
2. Cabeçalho Authorization (401 missing authorization header, invalid authorization format). O formato é Bearer <token>.
3. Token (401 invalid or expired token; 403 token_scope; 403 token not valid for this storefront; 401 token revoked (a mensagem completa segue pedindo novo login, em inglês)).
4. Tipo de usuário (403 insufficient permissions).
5. Privilégio (403 insufficient privileges, com privilege_required_any).
6. Limite de requisições (429), aplicado antes de tudo, por IP.

Exemplos reais

{ "error": "missing authorization header" }

{
  "error": "insufficient privileges",
  "privilege_required_any": ["view_orders", "manage_orders"]
}

{
  "error": "validation_failed",
  "fields": {
    "email": "required",
    "first_name": "required",
    "password": "required"
  }
}

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

Como tratar erros no código

# -i mostra o status e o X-Request-Id; --fail-with-body sai com código != 0 em 4xx/5xx
curl -i --fail-with-body "$BASE_URL/api/v1/admin/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN"

Erros comuns

• Tratar 400 e 422 de forma diferente sem necessidade. Ambos significam "corrija a requisição". Leia fields quando existir.
• Repetir automaticamente um 4xx. Só 401 (depois de renovar o token), 409 in_progress e 429 merecem nova tentativa. Um 400 repetido falha sempre.
• Repetir um 500 em uma criação sem chave de idempotência. Pode duplicar o registro; veja Idempotência.
• Esperar Content-Type: application/json em todo erro. Alguns vêm como text/plain; faça o parse do mesmo jeito.
• Perder o X-Request-Id. Registre-o em cada erro; é o que o suporte pede (Rastreamento de requisições).
• Mensagens em português. Algumas poucas mensagens de regra de negócio e de manutenção vêm em português da própria plataforma (loja em manutencao); trate-as como texto de exibição, não como código.

Veja também