Erros

Envelope {error:{code,message,details?}} e a tabela completa de códigos de erro com status HTTP e significado.

Todo erro usa o envelope abaixo. O campo details só aparece quando há detalhe estruturado (issues de validação, scopes, external_id não mapeados).

details pode estar ausente

Não conte com details: null. Quando não há detalhe estruturado, a chave details simplesmente não aparece no envelope.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Payload invalido.",
    "details": [ { "path": "items.0.quantity", "message": "items[].quantity deve ser > 0." } ]
  }
}

Códigos de erro

Código	Status	Significado
`FEATURE_DISABLED`	503	API ainda desabilitada no ambiente.
`INVALID_API_KEY`	401	Chave ausente, malformada, revogada ou inválida.
`AUTH_UNAVAILABLE`	503	Falha de infra na autenticação; a API fecha por segurança (fail-closed). Retry com backoff.
`INSUFFICIENT_SCOPE`	403	Chave sem o scope exigido (`details.required_scope`).
`FORBIDDEN_STORE`	403	Loja fora do escopo da chave (escritas de catálogo/estoque — por item no lote; resgate de cupom de fidelidade).
`VALIDATION_ERROR`	400	Payload inválido (também aparece por item nos lotes).
`NOT_FOUND`	404	Recurso inexistente ou fora do escopo da chave (sem vazar existência).
`CUSTOMER_NOT_FOUND`	404	Cliente de fidelidade não localizado (find-only) ou sem saldo/programa.
`NO_PROGRAM`	404	Nenhum programa de fidelidade ativo.
`INSUFFICIENT_BALANCE`	422	Débito de pontos maior que o saldo.
`COUPON_INVALID`	404/422	Cupom inexistente (404) ou inativo/expirado/limite atingido (422).
`SSRF_BLOCKED`	400	URL de webhook recusada pelo guard anti-SSRF.
`WEBHOOK_LIMIT_REACHED`	409	Limite de 5 webhooks por integração atingido.
`CONFLICT`	409	Corrida concorrente no crédito de pontos; re-tente.
`RATE_LIMITED`	429	Limite da chave excedido; respeite o `Retry-After`.
`INTERNAL`	500	Falha interna; retry com backoff.
`POINTS_UNAVAILABLE` / `COUPON_UNAVAILABLE`	503	Operação de fidelidade indisponível; re-tente com backoff.
`PRODUCT_NOT_FOUND`	por item	`PATCH /stock` com `external_id` que não existe no catálogo.
`STORE_WRITE_FAILED`	por item	Falha ao gravar estoque/preço de uma loja específica do item.

Como reagir

503 (FEATURE_DISABLED, AUTH_UNAVAILABLE, POINTS_UNAVAILABLE/COUPON_UNAVAILABLE) e 500 (INTERNAL): retry com backoff exponencial. Não é problema do seu payload.
429 (RATE_LIMITED): respeite o header Retry-After. Ver Rate limiting.
4xx de validação/escopo (400, 401, 403, 404, 422): corrija o payload, a chave ou o escopo — retry sem mudança vai falhar de novo.
409 CONFLICT: corrida concorrente no crédito de pontos; re-tente com a mesma idempotency_key. Ver Idempotência.

Códigos de erro

Como reagir

On this page