Gestión de errores REST API — España
Errores RFC 7807 problem+json, códigos estables y guía de reintento para la REST API en España.
Arquitectura — RFC 7807 problem+json en todos lados en España
Cada respuesta 4xx/5xx usa Content-Type: application/problem+json con campos: type (URI estable), title, status, detail, instance (request id) y campos de extensión por tipo. type es estable entre versiones y enlaza a la documentación con guía retry/fix. Loguea siempre instance — soporte lo traza end-to-end en menos de un minuto.
Cómo integrarlo — Catálogo de errores comunes
invalid_vat (no coincide con VIES, retry tras fix), invalid_sku (fuera del catálogo España, fix), min_qty_violation (debajo del MOQ, fix), invalid_tax_rate (no coincide con IVA 21%, fix), idempotency_conflict (misma key, body distinto, fix), insufficient_inventory (escalar o esperar), FACe/SII_unavailable (transitorio, retry con backoff). Catálogo completo en /docs/errors.
Operación y casos límite — Errores 5xx e idempotencia
Los errores 5xx significan que la petición no se confirmó. Logueamos request id, alertamos on-call, publicamos incidentes en la status page. Las idempotency keys te protegen: los retries con la misma key tras un 5xx nunca duplican el cobro. Nuestros SDKs reintentan 5xx con backoff exponencial (máx 3 intentos) — desactivable si prefieres control manual. Los fallos de FACe / Suministro Inmediato de Información (SII) llegan asíncronos vía webhook con sugerencias de retry.
Preguntas frecuentes
¿El catálogo de errores es estable?
Sí — los type URI están versionados y nunca reutilizamos un código. Los nuevos son aditivos.
¿Cómo correlaciono logs?
Cada respuesta tiene instance = request id (cm-req-…). Pásalo a soporte y trazamos end-to-end en menos de un minuto.
¿SDK o HTTP raw?
Los SDKs lanzan excepciones tipadas correspondientes al type URI — normalmente más simple que parsear JSON. Raw HTTP también funciona.
¿Y los errores de validación?
422 con array errors, una entrada por campo erróneo con código estable y mensaje legible.
¿FACe/SII_unavailable?
Transitorio — nuestro gateway buferiza el payload de factura y reintenta a FACe/SII. La confirmación llega vía webhook.