Conceptos

Errores

Todas las respuestas de error son JSON estándar RFC 7807 (Problem Details). Mismo shape para 4xx y 5xx, con un code machine-readable.

Formato RFC 7807

{
  "type": "https://docs.fiscal-web.pe/errors/quota_exceeded",
  "title": "Cuota Free excedida",
  "status": 402,
  "code": "quota_exceeded",
  "detail": "Has usado los 100 documentos gratis de este mes. Activa Pay-as-you-go para continuar.",
  "instance": "/v1/documents",
  "trace_id": "req_01HXYZ...",
  "errors": []
}

Campos:

type — URI con doc del error.
title — descripción corta human-readable.
status — código HTTP.
code — identificador machine-readable estable.
detail — explicación específica del caso.
instance — path o recurso afectado.
trace_id — ID único para soporte. Inclúyelo en el ticket.
errors — lista de problemas por campo (validation_failed).

Catálogo de códigos

Esta es la lista canónica vigente. Tu cliente HTTP debería usar code (no el texto de title) para ramificar lógica:

HTTP	code	Significado
`400`	`invalid_payload`	Body inválido o JSON malformado
`401`	`auth_required`	Falta o key inválida
`401`	`auth_expired`	Key revocada o expirada
`403`	`insufficient_scope`	Key sin permisos suficientes
`403`	`tenant_suspended`	Tenant suspendido por billing
`404`	`not_found`	Recurso inexistente
`409`	`idempotency_conflict`	Mismo key, body distinto
`409`	`document_state_conflict`	Acción incompatible con estado actual
`402`	`quota_exceeded`	Cuota Free agotada
`402`	`payment_required`	Subscripción past_due
`422`	`validation_failed`	Campos inválidos (ver `errors`)
`422`	`idempotency_key_missing`	Header Idempotency-Key faltante
`429`	`rate_limited`	Demasiadas peticiones (ver Retry-After)
`500`	`internal_error`	Bug nuestro — repórtalo
`503`	`fiscal_core_unavailable`	Fiscal-Core/SUNAT temporal

Estrategia de manejo

4xx (cliente) — fija tu request (no reintentes igual). Las únicas excepciones son rate_limited (espera el Retry-After) y red flakes.
5xx (servidor) — retry con backoff exponencial (200ms → 1s → 5s, máx 3 retries). fiscal_core_unavailable incluye Retry-After con segundos a esperar.
402 quota_exceeded — activa Pay-as-you-go desde /app/billing. Mientras tanto, sandbox sigue funcionando.
422 validation_failed — la lista errors trae field + message + code por cada campo inválido.

¿Te resultó útil esta página?