Errores

Todos los errores de la API siguen el mismo formato (envelope), independientemente del código HTTP.

Formato de error

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "El campo 'series' es requerido",
    "details": {
      "fields": {
        "series": "El campo 'series' es requerido"
      }
    }
  }
}

Códigos

Códigos
code	HTTP	Significado
`BAD_REQUEST`	400	Error de validación — revisa los campos indicados en details.fields.
`MISSING_TOKEN`	401	No se envió Authorization: Bearer <key>.
`API_KEY_REVOKED / API_KEY_EXPIRED / API_KEY_INACTIVE`	401	La key fue revocada, expiró o está desactivada.
`PERMISSION_DENIED`	403	La key no tiene el permiso necesario para esta operación (ej. invoices.send_sunat).
`NOT_FOUND`	404	El recurso solicitado no existe (o pertenece a otra empresa). Los recursos específicos traen su propio código, ej. INVOICE_NOT_FOUND.
`CONFLICT`	409	Conflicto con el estado actual (ej. CORRELATIVE_ALREADY_USED, IDEMPOTENCY_KEY_CONFLICT, OPERATION_IN_PROGRESS).
`DOMAIN_ERROR`	422	La solicitud es válida pero viola una regla de negocio. El código específico viene en code (ej. INVOICE_INCONSISTENT_TOTALS, SUPPLIER_ADDRESS_INCOMPLETE).
`CAPTCHA_INVALID`	400	Consulta pública: el captcha falta, expiró o no se pudo verificar.
`COMPROBANTE_NOT_FOUND`	404	Consulta pública: no hay un comprobante con exactamente esos datos.
`DOWNLOAD_TOKEN_INVALID`	400	Consulta pública: el token de descarga expiró o no es válido. Repite la consulta.
`FILE_NOT_AVAILABLE`	404	Consulta pública: ese archivo no está disponible para el comprobante.
`API_KEY_RATE_LIMIT_EXCEEDED`	429	Superaste el límite de solicitudes por minuto de la key. Revisa X-RateLimit-Remaining y Retry-After.
`INTERNAL_ERROR`	500	Error inesperado del servidor — reintenta más tarde.

Errores de validación (422)

Cuando varios campos fallan a la vez, details.fields trae una entrada por cada uno — úsalo para mapear el error directamente a tu formulario en lugar de parsear message.

Validación con múltiples campos

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "La solicitud tiene 2 errores de validación",
    "details": {
      "fields": {
        "series": "El campo 'series' es requerido",
        "items": "Debe incluir al menos un ítem"
      }
    }
  }
}

Reintentos

Ante un 500 INTERNAL_ERROR, reintenta con backoff exponencial (por ejemplo 1s, 2s, 4s) hasta 3 veces antes de escalar. Los códigos 4xx no son transitorios — reintentarlos sin corregir la solicitud siempre falla igual.