Troubleshooting
Erros comuns por código (401, 403, 409, 422, 503), webhook não entregue, diagnóstico de entregas e curl de health.
Guia rápido de diagnóstico. Para o detalhe semântico de cada código, veja Erros; para dúvidas conceituais, FAQ.
Health check
Comece sempre confirmando que a chave responde:
curl -sS https://api.onmia.com.br/integration/v1/health \
-H "X-API-Key: $ONMIA_API_KEY"200 { "status": "ok", ... }→ chave válida e ambiente ligado.503 FEATURE_DISABLED→ ambiente ainda não habilitado pela OnmIA (não é a sua chave).401 INVALID_API_KEY→ chave ausente/malformada/revogada.
Erros comuns por código
| Código | Status | Causa provável | O que fazer |
|---|---|---|---|
FEATURE_DISABLED | 503 | Ambiente desligado. | Confirmar o go-live com o contato OnmIA. Vale para tudo, inclusive /health. |
INVALID_API_KEY | 401 | Chave no formato errado, em Authorization em vez de X-API-Key, com espaços/quebras ao copiar, ou revogada/rotacionada. | Enviar X-API-Key: onmia_<key_id>_<secret> completo. Sem cache: a chave revogada morre na requisição seguinte. |
AUTH_UNAVAILABLE | 503 | Falha transitória na autenticação (fail-closed). | Retry com backoff. |
INSUFFICIENT_SCOPE | 403 | A chave não tem o scope da rota. | Ver details.required_scope × details.granted_scopes. Emitir/ajustar a chave com o scope que falta (Criar credencial). |
FORBIDDEN_STORE | 403 | store_id fora do escopo da chave (escrita de catálogo/estoque ou resgate de cupom). | Conferir o store_ids do /health. Nos lotes, aparece por item. |
VALIDATION_ERROR | 400 | Payload inválido (faltou campo, valor fora de regra). | Ler details[] (path + message) e corrigir. |
NOT_FOUND | 404 | Recurso inexistente ou fora do escopo da chave. | A API não confirma existência fora do escopo. Conferir id e escopo de loja. |
CUSTOMER_NOT_FOUND | 404 | Cliente de fidelidade não localizado (find-only). | Conferir phone (com/sem nono dígito) ou external_id. A fidelidade não cria cliente. |
INSUFFICIENT_BALANCE | 422 | Débito de pontos maior que o saldo. | Checar GET /loyalty/balance antes de debitar. |
COUPON_INVALID | 404/422 | Cupom inexistente (404) ou inativo/expirado/limite atingido (422). | Validar antes com POST /loyalty/coupons/validate. |
CONFLICT | 409 | Corrida concorrente no crédito de pontos. | Re-tentar com a mesma idempotency_key. |
SSRF_BLOCKED | 400 | URL de webhook não-HTTPS, IP privado/reservado ou hostname que não resolve. | Expor um endpoint HTTPS público que não resolve para faixa interna. |
WEBHOOK_LIMIT_REACHED | 409 | Mais de 5 webhooks por integração. | Remover um endpoint antes de criar outro. |
RATE_LIMITED | 429 | Estouro do token bucket (120/min por chave; 300/min por IP). | Respeitar Retry-After; backoff exponencial com jitter (Rate limiting). |
INTERNAL | 500 | Falha interna transitória. | Retry com backoff. |
Pedido não chega ao ERP (order.created)
- Confirme que o webhook está registrado com o evento
order.created:curl -sS https://api.onmia.com.br/integration/v1/webhooks \ -H "X-API-Key: $ONMIA_API_KEY"eventsdo endpoint precisa conterorder.created. - Dispare um teste de entrega e acompanhe o resultado:
curl -sS -X POST https://api.onmia.com.br/integration/v1/webhooks/$WEBHOOK_ID/test \ -H "X-API-Key: $ONMIA_API_KEY" - Crie um pedido de teste na loja de teste (catálogo, WhatsApp ou lançamento manual no dashboard) e confirme a entrega no log (abaixo).
Webhook não entregue — diagnóstico
curl -sS "https://api.onmia.com.br/integration/v1/webhooks/$WEBHOOK_ID/deliveries?limit=20" \
-H "X-API-Key: $ONMIA_API_KEY"Leia, por entrega, status, attempt_count, response_status e last_error:
| Sintoma | Causa | Correção |
|---|---|---|
last_error: HTTP 500 do endpoint do parceiro | Seu receptor respondeu não-2xx. | Corrigir o handler; responder 2xx em < 10s, persistindo antes. |
last_error cita faixa privada/reservada | DNS split-horizon resolve para IP interno. | Expor hostname com resolução pública. |
status: dead | 6 tentativas esgotadas (janela ~14h35min). | Não há re-entrega: reconcilie via GET /orders. Valide com /webhooks/:id/test. |
consecutive_failures alto em GET /webhooks | Seu receptor derruba entregas em série. | Corrigir e validar com /webhooks/:id/test (zera ao primeiro sucesso). |
response_status: 3xx | Redirecionamento (conta como falha). | Apontar a URL direto para o destino final — 3xx não é seguido. |
Requisitos do receptor (todos obrigatórios): HTTPS, host público, sem
redirect, resposta 2xx em até 10 s. Detalhes em
Webhooks.
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>", comparando em tempo constante. Exemplos em Node, PHP e
Python na página de Webhooks.
404 ao chamar POST /integration/v1/orders
Esperado — a rota foi removida em v1.1. O ERP não cria pedidos: recebe
via order.created (Pedidos).