Errores
Formato de errores, códigos de estado y los errores propios de SUNAT.
La API usa códigos de estado HTTP convencionales y devuelve un cuerpo de error consistente para que puedas manejarlo de forma programática.
Formato del error
{
"error": {
"type": "invalid_request_error",
"code": "parameter_missing",
"message": "El campo customer.document_number es obligatorio.",
"param": "customer.document_number"
}
}| Campo | Descripción |
|---|---|
type | Categoría del error (ver abajo). |
code | Código estable y legible por máquina. |
message | Mensaje descriptivo para humanos. |
param | Campo que causó el error, si aplica. |
Códigos de estado
| Código | Significado | Cuándo ocurre |
|---|---|---|
200 / 201 | OK | La solicitud tuvo éxito. |
202 | Accepted | El comprobante quedó en cola para SUNAT. El resultado llega por webhook. |
400 | Bad Request | La solicitud está mal formada. |
401 | Unauthorized | API key ausente o inválida. |
402 | Payment Required | Tu cuenta superó el tope de crédito del mes. |
403 | Forbidden | La key no puede usar ese emisor. |
404 | Not Found | El recurso no existe. |
409 | Conflict | Conflicto de estado o de idempotencia. |
422 | Unprocessable | Un campo no cumple una regla, nuestra o de SUNAT. |
429 | Too Many Requests | Superaste el límite de tasa. |
5xx | Server Error | Falla nuestra. Reintenta con la misma Idempotency-Key. |
Conflictos (409)
error.code | Qué pasó |
|---|---|
idempotency_key_reused | Usaste una Idempotency-Key con un cuerpo distinto al original. |
invoice_not_voidable | Solo se anulan comprobantes accepted u observed. |
void_window_expired | Pasaron más de 7 días; emite una nota de crédito en su lugar. |
cdr_not_available | SUNAT aún no respondió. Espera el webhook. |
Rechazos de SUNAT
Un comprobante aceptado por nosotros (202) todavía puede ser rechazado por SUNAT.
No es un error HTTP: es un cambio de estado a rejected, con el código y el mensaje de
SUNAT en status_history. Lo recibes en el webhook invoice.rejected.
{
"status": "rejected",
"status_history": [
{ "status": "pending", "at": "2026-11-02T15:04:05Z" },
{ "status": "sent", "at": "2026-11-02T15:04:06Z" },
{ "status": "rejected", "at": "2026-11-02T15:04:09Z", "sunat_code": "2017", "message": "El RUC del receptor no existe" }
]
}Un comprobante rechazado no se corrige: emite uno nuevo con los datos correctos. El correlativo rechazado queda registrado así ante SUNAT y no se reutiliza.
Dar de alta un emisor no es inmediato
Registrar un RUC nuevo dispara un alta ante SUNAT que suele completarse al día siguiente. No es instantáneo y no depende de nosotros: lo ejecuta el proveedor de firma y lo aprueba SUNAT, que a veces tiene intermitencias.
Mientras tanto el emisor está en status: "pending" y cualquier emisión devuelve 409:
{
"error": {
"type": "invalid_request_error",
"code": "issuer_not_ready",
"message": "El alta de este RUC ante SUNAT todavía está en curso. Suele estar listo al día siguiente.",
"param": "issuer_id"
},
"available_at": "2026-11-03T14:20:00Z"
}Esto es deliberado y te ahorra plata. El correlativo se asigna al crear el comprobante,
antes de que SUNAT opine, así que un intento contra un RUC que todavía no está habilitado
gasta un número de serie que no se recupera. Preferimos devolverte un 409 barato.
| Código | Qué pasó | Qué hacer |
|---|---|---|
issuer_not_ready | El alta sigue en curso. | Espera a available_at y reintenta. |
issuer_not_authorized | SUNAT rechazó el RUC (0111 o 0154). | Lee status_detail: tu cliente debe resolverlo en SUNAT. |
issuer_not_configured | La empresa sigue en prueba. | Pásala a producción desde la consola (Mis empresas). |
Si el emisor queda not_authorized
Son dos causas, las dos del lado del contribuyente y ninguna se arregla reintentando:
0111— el RUC no está habilitado como emisor electrónico. Se habilita desde SUNAT con la clave SOL.0154— el RUC no autorizó al proveedor de firma (PSE). También se hace desde la clave SOL del contribuyente.
Bloqueamos al emisor en cuanto SUNAT responde alguno de los dos. No es una limitación: es lo que evita que tu integración siga gastando correlativos contra un problema que sólo puede resolver tu cliente.