Tratamento de erros
Interprete os códigos de status e o envelope padrão de respostas do Ecom.
4 min de leituraAtualizado em 2 de agosto de 2026
As respostas seguem um envelope consistente. Sucesso: { success: true, data }. Erro (rotas internas): { success: false, error }.
json
{
"success": false,
"error": "O campo 'email' é obrigatório."
}A API pública /api/v1 usa um envelope estável próprio para erros:
json
{
"error": { "code": "BAD_REQUEST", "message": "Identificador invalido" }
}Códigos comuns
- 400 / 422 — requisição inválida ou falha de validação.
- 401 — sessão ausente/expirada, cookie inválido ou tenant divergente.
- 403 — sem permissão RBAC ou sem escopo na chave de API.
- 404 — recurso não encontrado (ou de outro tenant/cliente).
- 429 — limite de taxa excedido.
- 503 — recurso externo não configurado (ex.: gateway de pagamento).