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; nos lotes aparece por item).
`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).
`UNMAPPED_ITEMS`	422	Pedido contém `external_id` sem produto mapeado (`details.unmapped_external_ids`).
`PROCESSING_IN_FLIGHT`	409	Mesmo `external_order_id` em processamento concorrente. Retry com backoff, mesmo id.
`INVALID_TRANSITION`	409	Transição de status rejeitada pela máquina de estados.
`INSUFFICIENT_STOCK`	400	Estoque insuficiente (apenas chaves com decremento opt-in).
`SSRF_BLOCKED`	400	URL de webhook recusada pelo guard anti-SSRF.
`WEBHOOK_LIMIT_REACHED`	409	Limite de 5 webhooks por integração atingido.
`RATE_LIMITED`	429	Limite da chave excedido; respeite o `Retry-After`.
`INTERNAL`	500	Falha interna; retry 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) 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 PROCESSING_IN_FLIGHT: reenvie com backoff e o mesmo external_order_id. Ver Idempotência.

Códigos de erro

Como reagir

On this page