FAQ

Solução de problemas — 503, 401, 403, 422, 409, por que o estoque não baixa e o que fazer quando o webhook não chega.

Respostas para os erros e dúvidas mais comuns na integração. Para o detalhe de cada código, veja a página de Erros.

`503 FEATURE_DISABLED` em tudo, inclusive `/health`?

O ambiente ainda não foi habilitado pela OnmIA. Não é problema da sua chave — enquanto o ambiente está desligado, toda chamada retorna 503. Confirme com o contato OnmIA o status do go-live.

`401 INVALID_API_KEY` mas a chave "parece certa"?

Envie a chave completa no formato onmia_<key_id>_<secret> no header X-API-Key — não em Authorization, sem Bearer.
Confira espaços e quebras de linha ao copiar do cofre.
Se a chave foi rotacionada, a antiga morre imediatamente (não há cache de credencial).

`403 INSUFFICIENT_SCOPE` vs. `403 FORBIDDEN_STORE`?

INSUFFICIENT_SCOPE: sua chave não tem a permissão da rota (veja details.granted_scopes). Peça à OnmIA o scope que falta.
FORBIDDEN_STORE: a chave tem o scope, mas o store_id enviado está fora da lista de lojas da chave. Confira o store_ids retornado pelo /health.

`422 UNMAPPED_ITEMS` ao criar pedido?

Um ou mais external_id dos itens não existem no catálogo OnmIA (details.unmapped_external_ids lista quais). Cadastre os produtos via POST /products/bulk antes de enviar pedidos com eles. O pedido não foi criado — sem efeito parcial.

`409 PROCESSING_IN_FLIGHT` ao criar pedido?

Outra requisição com o mesmo external_order_id ainda está processando (retry agressivo, timeouts curtos demais). Aguarde com backoff e reenvie com o mesmo id — você receberá 201 ou o replay 200.

Nunca troque o external_order_id

Mudar o id para "destravar" um 409 duplica o pedido. Sempre reenvie o mesmo id. Ver Idempotência.

Por que o estoque não baixa quando crio um pedido?

Design intencional. O ERP é a autoridade de estoque: a venda já decrementou no seu sistema, então envie o saldo novo via PATCH /stock. Decremento automático existe apenas como opt-in por chave, combinado na emissão.

Webhook não chega?

Confira os requisitos do receptor: HTTPS, host público, sem redirect, resposta 2xx em menos de 10s.
Consulte GET /webhooks/:id/deliveries e leia status, attempt_count, response_status e last_error — eles dizem exatamente o que o worker viu (ex.: HTTP 500 do endpoint do parceiro, bloqueio SSRF, timeout).
last_error mencionando faixa privada/reservada: seu DNS está resolvendo para IP interno (split-horizon DNS). Exponha um hostname com resolução pública.
consecutive_failures alto em GET /webhooks: seu receptor está derrubando entregas em série; corrija e valide com POST /webhooks/:id/test.
Entrega dead não volta: reconcilie via GET /orders e siga — novos eventos entram normalmente.

Assinatura HMAC nunca bate?

99% dos casos: o framework fez parse do JSON e você re-serializou. Capture o raw body (bytes) antes do middleware de JSON e assine sobre "<timestamp>.<raw_body>". Detalhes em Webhooks.

On this page