Errores

Formato de los errores y lista completa de códigos.

Todos los errores tienen la misma forma:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "items.0.taxCode: Debe ser uno de: 10, 11, 12, 13, 14, 15, 16, 20, 21, 30, 31, 32, 33, 34, 35, 36, 37, 40.",
    "retryable": false,
    "fields": {
      "items.0.taxCode": ["Debe ser uno de: 10, 11, 12, 13, 14, 15, 16, 20, 21, 30, 31, 32, 33, 34, 35, 36, 37, 40."]
    },
    "requestId": "2112f495-00c4-4844-b750-86200f1a391e"
  }
}

Campo	Descripción
`code`	Código estable en inglés. Tu integración debe decidir por este valor.
`message`	Explicación en español. Puede cambiar; no la compares en tu código.
`retryable`	`true` si repetir la misma petición más tarde puede funcionar.
`fields`	Errores por campo, con la ruta del campo (`customer.documentType`, `items.0.quantity`). Vacío si el error no es de un campo.
`requestId`	Identificador de la petición. También llega en el header `X-Request-Id`.

Cada código tiene siempre el mismo estado HTTP.

Cómo reaccionar

retryable: false: corrige la petición. Reintentarla igual dará el mismo error.
retryable: true: reintenta con espera creciente (por ejemplo 1, 2, 4 y 8 segundos). En 429 respeta el header Retry-After. En emisiones, reintenta con la misma Idempotency-Key.
Campos desconocidos: un campo que no existe en el contrato responde VALIDATION_ERROR con el mensaje "El campo no está permitido.". Revisa el nombre del campo.

Rechazos de SUNAT

Un comprobante que SUNAT rechaza no es un error HTTP: la emisión responde 202 con status: "rejected" y el detalle en sunat.errorCode y sunat.errorMessage. Ver Estados.

Códigos

Código	HTTP	Reintentable	Significado
`IDEMPOTENCY_REQUIRED`	400	No	Falta el header `Idempotency-Key`.
`VALIDATION_ERROR`	400	No	El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.
`UNAUTHENTICATED`	401	No	Falta la clave API o no es válida.
`ISSUER_LIMIT_REACHED`	402	No	El plan no permite más RUC de producción. Los RUC de prueba no cuentan.
`PLAN_LIMIT_REACHED`	402	No	Se consumieron las operaciones del plan en el mes.
`PLAN_REQUIRED`	402	No	El workspace no tiene una suscripción activa.
`TRIAL_EXHAUSTED`	402	No	La prueba gratuita consumió sus operaciones.
`TRIAL_EXPIRED`	402	No	La prueba gratuita venció.
`FORBIDDEN`	403	No	La operación no está permitida.
`ISSUER_FORBIDDEN`	403	No	El RUC no pertenece al workspace de la clave.
`LIVE_KEY_REQUIRED`	403	No	La operación requiere una clave `asu_live_`.
`PRODUCTION_NOT_ENABLED`	403	No	Usaste una clave `asu_live_` con un RUC que todavía no tiene producción habilitada. Usa una clave `asu_test_` para probar o completa la validación de producción.
`TEST_KEY_IN_PRODUCTION`	403	No	Intentaste actuar sobre un documento con el otro tipo de clave: un documento emitido con `asu_live_` se maneja con una clave live, y uno de prueba con una clave test. También aparece si una clave test intenta activar o desactivar un RUC con producción habilitada. No aparece al emitir.
`WORKSPACE_SUSPENDED`	403	No	El workspace está suspendido.
`ISSUER_NOT_FOUND`	404	No	El RUC no está registrado en el workspace en el modo de la clave.
`NOT_FOUND`	404	No	El recurso no existe en el workspace.
`BETA_VALIDATION_REQUIRED`	409	No	Valida primero el RUC de prueba en beta antes de emitir con él.
`CONFLICT`	409	No	El estado actual del recurso no permite la operación.
`DOCUMENT_NUMBER_CONFLICT`	409	No	La serie y número ya fueron emitidos.
`EMAIL_IN_PROGRESS`	409	Sí	Ya hay un envío de correo en curso para el documento.
`FILES_NOT_AVAILABLE`	409	Sí	El XML, ZIP o PDF todavía no está disponible.
`IDEMPOTENCY_CONFLICT`	409	No	La `Idempotency-Key` ya se usó con otro cuerpo.
`ISSUER_ALREADY_EXISTS`	409	No	El RUC ya está registrado en el modo de la clave.
`ISSUER_NOT_CONFIGURED`	409	No	El RUC no tiene credenciales SUNAT listas.
`ISSUER_SELECTION_REQUIRED`	409	No	Tu plan ya tiene el máximo de RUC activos; desactiva el RUC activo antes de activar otro.
`PRODUCTION_CREDENTIALS_REQUIRED`	409	No	Guarda las credenciales del RUC (usuario SOL y certificado) antes de la prueba real.
`PRODUCTION_INVOICE_PENDING`	409	No	La factura de validación de producción sigue pendiente.
`PRODUCTION_VALIDATION_REQUIRED`	409	No	El RUC necesita una validación de producción aceptada.
`LIVE_MODE_ISSUER`	409	No	El RUC es de producción: la validación en SUNAT beta se hace con el RUC de prueba y una clave `asu_test_`.
`REQUEST_IN_PROGRESS`	409	Sí	Otra petición con la misma `Idempotency-Key` sigue en proceso.
`SERIES_BUSY`	409	Sí	La serie está reservada por otra emisión; reintenta.
`SERIES_DUPLICATED`	409	No	La serie ya existe en el RUC.
`TEST_MODE_ISSUER`	409	No	El RUC es de prueba: la prueba real y la habilitación de producción se hacen en el RUC de producción con una clave `asu_live_`.
`VALIDATION_IN_PROGRESS`	409	Sí	Ya hay una validación del RUC en curso.
`CONFIRMATION_REQUIRED`	422	No	Falta la confirmación exacta para emitir en producción.
`CUSTOMER_NOT_FOUND`	422	No	No se encontraron datos para el RUC o DNI del cliente; envía `customer.name`.
`EXPORT_DATA_INCOMPLETE`	422	No	Faltan datos obligatorios de exportación (operación 0200).
`INVALID_EMAIL`	422	No	El destinatario no es un correo válido.
`INVALID_ESTABLISHMENT`	422	No	El establecimiento no existe o no pertenece al RUC.
`INVALID_LOGO`	422	No	El logo debe ser PNG o JPEG en base64.
`INVALID_SERIES`	422	No	La serie no existe o no corresponde al tipo de documento.
`NOTE_ISSUER_MISMATCH`	422	No	La nota y el documento afectado son de RUC distintos.
`NUMBER_REQUIRED`	422	No	La serie es manual y requiere `number`.
`SERIES_ESTABLISHMENT_MISMATCH`	422	No	La serie pertenece a otro establecimiento.
`SERIES_INACTIVE`	422	No	La serie está inactiva.
`TAX_NOT_CONFIGURED`	422	No	No hay un impuesto válido para la afectación indicada.
`VOID_MIXED_DOCUMENTS`	422	No	Las boletas se anulan en una petición separada de facturas y notas.
`VOID_NOT_ALLOWED`	422	No	Solo se anulan documentos aceptados por SUNAT.
`VOID_SUMMARY_MISMATCH`	422	No	Las boletas de un resumen deben compartir RUC, fecha y moneda.
`RATE_LIMITED`	429	Sí	Se superó el límite de peticiones. Respeta el header `Retry-After`.
`INTERNAL_ERROR`	500	Sí	Error interno. Reintenta y comparte el `requestId` con soporte.
`LOOKUP_UNAVAILABLE`	503	Sí	La consulta de RUC o DNI no está disponible; reintenta o envía `customer.name`.
`SERVICE_UNAVAILABLE`	503	Sí	Un servicio interno no responde. Reintenta en unos segundos.