Gestão de erros REST API — Portugal
Erros RFC 7807 problem+json, códigos estáveis e orientações de retry para a REST API em Portugal.
Arquitectura — RFC 7807 problem+json em toda parte em Portugal
Cada resposta 4xx/5xx usa Content-Type: application/problem+json com campos: type (URI estável), title, status, detail, instance (request id) e campos de extensão por tipo. O type é estável entre versões e liga à documentação com orientações retry/fix. Logue sempre instance — o suporte rastreia end-to-end em menos de um minuto.
Como integrar — Catálogo de erros comuns
invalid_vat (não bate com VIES, retry após fix), invalid_sku (fora do catálogo Portugal, fix), min_qty_violation (abaixo do MOQ, fix), invalid_tax_rate (não bate com IVA 23%, fix), idempotency_conflict (mesma key, body diferente, fix), insufficient_inventory (escalar ou aguardar), AT_unavailable (transitório, retry com backoff). Catálogo completo em /docs/errors.
Operação e casos extremos — Erros 5xx e idempotência
Erros 5xx significam que a chamada não foi confirmada. Logamos request id, alertamos on-call, publicamos incidentes na status page. Idempotency keys protegem-te: retries com a mesma key após 5xx nunca cobram em duplicado. Os nossos SDKs fazem retry de 5xx com backoff exponencial (máx. 3 tentativas) — desactivável se quiseres controlo manual. Falhas Portal das Finanças (AT) chegam assíncronas via webhook com sugestões de retry.
Perguntas frequentes
O catálogo de erros é estável?
Sim — type URIs são versionados e nunca reutilizamos um código. Novos são aditivos.
Como correlacionar logs?
Cada resposta tem instance = request id (cm-req-…). Passa ao support, rastreamos end-to-end em menos de um minuto.
SDK ou HTTP raw?
Os SDKs lançam excepções tipadas correspondentes ao type URI — normalmente mais simples que parsing JSON. Raw HTTP também funciona.
E os erros de validação?
422 com array errors, uma entrada por campo errado com código estável e mensagem humana.
AT_unavailable?
Transitório — o nosso gateway buferiza o payload da factura e retry para AT. Confirmação por webhook.