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

{ "status": 404, "message": "Product not found" }

Mais exemplos reais: {"message":"user_id is required","status":400} (campo obrigatório) e {"message":"Invalid credentials","status":401}. A mensagem é uma frase curta; não há campos extras.

A rota POST /api/v1.0/auth_tokens responde por conta própria: {"error":"invalid credentials"} (401), {"message":"Required field: password"} (400) e {"error":"invalid JSON"} (400), sem o campo status.

Códigos HTTP

Exemplos reais

Falta a credencial (401)

{ "status": 401, "message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>." }

Chave incorreta (401)

{ "status": 401, "message": "Invalid credentials" }

Sem permissão (403)

{ "status": 403, "message": "Forbidden: admin scope required" }

Registro inexistente (404)

{ "message": "Order not found", "status": 404 }

Validação (400)

{ "message": "product (name) is required", "status": 400 }

{ "message": "shipping_service_unavailable: a shipping method is required for physical products", "status": 400 }

Id malformado (500 em algumas rotas)

Algumas rotas não validam o formato do id e respondem 500 com a descrição do problema na mensagem. Valide o UUID no seu sistema antes de enviar:

{ "message": "Failed to retrieve product", "status": 500 }

Tempo esgotado (503)

Uma rota que demora demais é interrompida pela plataforma e responde 503. Trate como erro repetível.

Erros que acontecem antes da sua rota

Duas 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. A autenticação (Autenticação): 401 e 403 com as mensagens da tabela daquela página.

Como tratar erros no seu código

1. Olhe o código HTTP primeiro

   2xx segue em frente. 401 pede um token novo (ou revê a chave). 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. A descrição está em message.

3. Repita só o que é seguro repetir

   Nunca repita um 400, 403 ou 404 sem mudar algo. Para criações (pedido), confira antes se o registro já existe (Limites e boas práticas).

Erros comuns

• Procurar o campo error. Aqui a descrição está em message; só a rota auth_tokens usa error.
• Repetir um 400 em loop. Ele nunca passa sem mudança.
• Fazer if mensagem == "...". Use o código HTTP.
• Ignorar o 500 numa consulta por id. Em geral é um id malformado.

Veja também