Erros

Erros usam o envelope padrão com error.code estável.

HTTP	Código	Quando acontece	O que fazer
400	BAD_REQUEST	Requisição inválida (ex.: falta Idempotency-Key).	Corrija a requisição.
400	INVALID_JSON	Corpo não é JSON válido.	Envie JSON válido.
401	MISSING_API_KEY	Nenhuma chave enviada.	Envie Authorization: Bearer ….
401	INVALID_API_KEY	Chave desconhecida.	Confira a chave.
401	API_KEY_REVOKED	Chave revogada.	Gere outra no painel.
401	API_KEY_EXPIRED	Chave expirada.	Gere outra no painel.
401	API_KEY_INACTIVE	Chave inativa.	Reative ou gere outra.
403	INSUFFICIENT_PERMISSIONS	A chave não tem a permissão do endpoint.	Ajuste as permissões.
403	MERCHANT_INACTIVE	Lojista vinculado não está ativo.	Fale com o suporte.
403	MERCHANT_SUSPENDED	Lojista suspenso.	Fale com o suporte.
403	MERCHANT_BLOCKED	Lojista bloqueado.	Fale com o suporte.
403	FORBIDDEN	Acesso negado ao recurso.	—
404	NOT_FOUND	Recurso não existe (ou não pertence ao seu lojista).	Confira o id.
404	ROUTE_NOT_FOUND	Endpoint inexistente.	Confira a URL.
405	METHOD_NOT_ALLOWED	Método HTTP não suportado no endpoint.	Use o método correto.
409	CONFLICT	Idempotency-Key reutilizada com outro corpo, ou em uso.	Use outra chave / aguarde e repita.
422	VALIDATION_ERROR	Campos inválidos. Veja error.details.fields.	Corrija os campos apontados.
422	RISK_LIMIT_EXCEEDED	Limite de risco do lojista excedido.	Fale com o suporte.
429	RATE_LIMITED	Muitas requisições.	Aguarde Retry-After.
500	INTERNAL_ERROR	Erro interno.	Tente de novo; informe o x-request-id.
503	RATE_LIMIT_UNAVAILABLE	Proteção de abuso indisponível por instantes.	Tente de novo em instantes.

Boas práticas

• Repita apenas erros transitórios: 409 (em processamento), 429, 500 e 503 — sempre com a mesma Idempotency-Key nas operações de criação.
• Não repita 4xx sem corrigir a causa.
• Ao abrir um chamado, informe o header x-request-id da resposta.