Errores
Formato
Sección titulada «Formato»Toda falla controlada responde con un código estable en reason y, a veces, una lista de details:
{ "reason": "ValidationFailed", "details": ["items.0.quantity:Gt", "items.0.unit_price:Decimal"]}reasones un código estable, en inglés y sin espacios. Tu sistema decide qué mensaje mostrar a su usuario, en su idioma. La API nunca devuelve prosa que tengas que interpretar.details(opcional) detalla la causa. En validaciones tiene la formacampo:Regla, con la ruta del campo en notación de puntos (items.0.quantityes la cantidad del primer ítem).
Los errores inesperados (500) no exponen detalles internos; solo devuelven el identificador de correlación:
{ "traceId": "01a1d5fc-8a30-7f4b-9c1e-6d2f0b7e5a11" }Ese valor coincide con la cabecera X-Request-Id. Repórtalo a soporte para ubicar el error exacto.
Códigos generales
Sección titulada «Códigos generales»| Estado | reason |
Qué hacer |
|---|---|---|
400 |
BadRequest |
Revisa que el cuerpo sea JSON válido. |
401 |
Unauthenticated |
Revisa tu API key (Autenticación). |
403 |
Forbidden, EmitterInactive |
Tu empresa no puede emitir; contacta a soporte. |
404 |
NotFound |
El recurso no existe o pertenece a otro emisor o entorno. |
405 |
MethodNotAllowed |
Método HTTP incorrecto para esa ruta. |
409 |
IdempotencyKeyReused, EmitterNotReadyForProduction, CertificateExpired |
Ver la tabla de emisión. |
413 |
PayloadTooLarge |
El cuerpo excede el tamaño permitido. |
422 |
ValidationFailed y códigos de negocio |
Corrige los datos; reintentar igual no cambia el resultado. |
429 |
TooManyRequests, EmailLimitReached |
Espera Retry-After segundos antes de reintentar (Límite de peticiones). |
500 |
— (solo traceId) |
Reintenta con la misma Idempotency-Key; si persiste, reporta el traceId. |
503 |
ServiceUnavailable, NotReady |
Servicio temporalmente no disponible; reintenta con espera. |
Errores de emisión (POST /v1/invoices, POST /v1/receipts)
Sección titulada «Errores de emisión (POST /v1/invoices, POST /v1/receipts)»| Estado | reason |
Causa |
|---|---|---|
422 |
ValidationFailed |
Falta un campo, el tipo no corresponde o un valor no está permitido. Ver details. |
422 |
InvalidIdempotencyKey |
La cabecera Idempotency-Key tiene caracteres no permitidos o más de 100. |
422 |
InvalidSeriesCode |
La serie no corresponde al tipo: las facturas usan F### y las boletas B###. |
422 |
SeriesUnavailable |
La serie no existe en el entorno de tu clave, está inactiva o agotó sus 8 dígitos. |
422 |
InvoiceRequiresCustomerRuc |
Una factura exige cliente con RUC. |
422 |
ReceiptRequiresCustomerDocument |
Boleta de más de S/ 700, o en dólares, sin documento del cliente. |
422 |
InvalidCustomerDocument |
DNI que no tiene 8 dígitos, RUC con dígito verificador incorrecto, CE o pasaporte con formato inválido. |
422 |
InvalidCustomerName |
Cliente identificado sin nombre, o nombre de más de 200 caracteres. |
422 |
NoItems, TooManyItems |
Sin ítems o con más de 500. |
422 |
InvalidDescription |
Ítem con descripción vacía o de más de 500 caracteres. |
422 |
InvalidQuantity, InvalidUnitPrice |
Cantidad o precio cero, negativo o con más de 10 decimales. |
422 |
ZeroTotal |
El total redondeado es S/ 0.00 y no hay operaciones gratuitas. |
422 |
CreditOnlyForInvoices |
Pago al crédito en una boleta. |
422 |
InvalidInstallments |
Crédito sin cuotas, más de 60 cuotas, cuota de monto cero o que vence en la fecha de emisión o antes. |
422 |
InstallmentsDoNotMatchTotal |
Las cuotas no suman exactamente el neto pendiente de pago (total menos detracción y retención). |
422 |
InvalidDiscount |
Descuento en cero, porcentaje de 100 o más, descuento global demasiado pequeño, o descuento en ítems de una nota. |
422 |
DiscountExceedsAmount |
El descuento iguala o supera el monto al que se aplica. |
422 |
DiscountNotAllowedOnFreeItem |
Descuento en un ítem gratuito. |
422 |
GlobalDiscountRequiresTaxedItems |
Descuento global en un comprobante sin ítems gravados. |
422 |
DetractionOnlyForInvoices, RetentionOnlyForInvoices |
Detracción o retención en una boleta. |
422 |
InvalidDetractionCode, InvalidDetractionPercent, InvalidDetractionAccount, InvalidDetractionPaymentMethod |
Código de bien o servicio, porcentaje, cuenta o medio de pago de la detracción con formato inválido. |
422 |
DetractionRequiresExchangeRate |
Detracción en dólares sin exchange_rate. |
422 |
RetentionRequiresPen, RetentionBelowThreshold |
Retención en dólares o con total de S/ 700 o menos. |
422 |
RetentionNotAllowedWithDetraction |
Retención y detracción a la vez. |
422 |
InvalidIssueDate |
issue_date futura o anterior al máximo permitido (3 días). |
422 |
InvalidServiceCharge |
Recargo al consumo sobre un valor de venta en cero. |
422 |
InvalidPurchaseOrder, InvalidDespatchReference, InvalidObservations, InvalidDueDate, InvalidSunatProductCode |
Dato comercial con formato inválido o vencimiento anterior a la emisión. |
409 |
IdempotencyKeyReused |
Usaste una Idempotency-Key ya usada, con otro cuerpo (Idempotencia). |
409 |
EmitterNotReadyForProduction |
Clave live sin certificado digital o usuario SOL configurado. |
409 |
CertificateExpired |
Clave live y el certificado digital del emisor venció: SUNAT rechazaría el comprobante. No se consume el correlativo; renueva el certificado. |
403 |
EmitterInactive |
La empresa emisora está desactivada. |
Errores de notas
Sección titulada «Errores de notas»Además de los de emisión:
| Estado | reason |
Causa |
|---|---|---|
422 |
AffectedDocumentNotFound |
affected_document_id no existe en tu empresa y entorno. |
422 |
InvalidAffectedDocument |
El comprobante afectado es una nota; solo se modifican facturas y boletas. |
409 |
AffectedDocumentNotAccepted |
El comprobante afectado aún no fue aceptado por SUNAT. |
409 |
AffectedDocumentVoided |
El comprobante afectado está anulado o tiene una anulación en curso. |
422 |
InvalidNoteReason |
reason_code no existe o no está soportado para ese tipo de nota. |
422 |
InvalidNoteDescription |
reason_description de más de 250 caracteres. |
422 |
NoteSeriesMismatch |
La serie de la nota no empieza con la misma letra que la del comprobante (F o B). |
422 |
NoteIssuedBeforeAffected |
issue_date de la nota es anterior a la fecha de emisión del comprobante afectado. |
422 |
NoteItemsRequired |
El motivo exige enviar items. |
422 |
NoteItemsNotAllowed |
El motivo 13 (ajuste de montos y/o fechas de pago) no admite items. |
422 |
CreditNoteExceedsAffectedTotal |
La nota de crédito supera el total del comprobante. |
422 |
CreditNotesExceedAffectedTotal |
Con esta nota, las notas de crédito acumuladas superarían el total del comprobante afectado. |
422 |
PaymentAdjustmentRequiresCreditInvoice |
El motivo 13 exige que el comprobante afectado sea una factura al crédito. |
422 |
PaymentAdjustmentRequiresInstallments |
El motivo 13 exige enviar el nuevo cronograma en payment.installments. |
422 |
InstallmentsExceedPendingAmount |
En el motivo 13, las cuotas suman más que el neto pendiente (net_payable) de la factura afectada. |
422 |
PaymentOnlyForAdjustmentNotes |
Se envió payment en una nota cuyo motivo no es el 13. |
Errores de anulación
Sección titulada «Errores de anulación»| Estado | reason |
Causa |
|---|---|---|
404 |
NotFound |
El comprobante no existe en tu empresa y entorno. |
409 |
DocumentNotAccepted |
SUNAT aún no aceptó el comprobante. |
409 |
VoidAlreadyRequested |
Ya hay una anulación en curso. |
409 |
AlreadyVoided |
El comprobante ya fue anulado. |
409 |
EmitterNotReadyForProduction |
Clave live sin certificado o usuario SOL. |
409 |
CertificateExpired |
Clave live y el certificado digital del emisor venció. |
422 |
InvalidVoidReason |
Motivo vacío o de más de 100 caracteres. |
422 |
VoidWindowExpired |
Pasó el plazo de anulación; emite una nota de crédito. |
409 |
DocumentHasNotes |
El comprobante tiene notas vigentes: anúlalas primero. |
Errores de webhooks y consultas
Sección titulada «Errores de webhooks y consultas»| Estado | reason |
Causa |
|---|---|---|
422 |
InvalidWebhookUrl |
URL que no es HTTPS, con credenciales, que no resuelve o que apunta a una red privada. |
422 |
InvalidWebhookEvents |
Evento desconocido. |
422 |
InvalidRecipients |
Lista de destinatarios de correo vacía, con más de 5 correos o con formato inválido. |
409 |
DocumentNotAccepted |
Envío por correo de un comprobante que SUNAT aún no aceptó. |
409 |
DocumentNotRetryable |
Reenvío de un comprobante que no está failed. |
409 |
DocumentRejected |
PDF de un comprobante rechazado por SUNAT. |
403 |
ApiKeyScopeInsufficient |
Clave de alcance lookup en una ruta que exige alcance completo. |
503 |
EmailNotConfigured |
Envío por correo no habilitado en el servicio. |
429 |
EmailLimitReached |
Se alcanzó el tope de correos del comprobante (10) o del emisor por hora (100). |
409 |
TooManyWebhooks |
Ya tienes 10 endpoints activos. |
422 |
InvalidRuc, InvalidDni |
Formato inválido. |
404 |
RucNotFound, DniNotFound |
No figura en el padrón de SUNAT o en la fuente de DNI. |
503 |
RucLookupUnavailable, DniLookupUnavailable |
El servicio de consulta de RUC o DNI no está disponible temporalmente. |
Observaciones, rechazos y fallos de envío ante SUNAT
Sección titulada «Observaciones, rechazos y fallos de envío ante SUNAT»El resultado de SUNAT no es un error HTTP al emitir: la emisión responde 201 Created con status: "pending" y el veredicto de SUNAT se refleja después en el comprobante (por webhook o en GET /v1/documents/{id}). Es importante distinguir los tres escenarios:
status |
Qué significa | ¿El comprobante es válido? | Qué debe hacer tu sistema |
|---|---|---|---|
observed |
SUNAT aceptó el comprobante (sunat.code: "0"), pero incluyó advertencias en sunat.notes (códigos 4000 o mayores, p. ej. 4252). |
Sí, 100 % válido. | Entrégalo normalmente al cliente y revisa sunat.notes para ajustar futuras emisiones. |
rejected |
SUNAT rechazó el comprobante por una regla fiscal o de datos (códigos 2000 a 3999 en sunat.code y detalle en sunat.description). |
No tiene validez tributaria. | Corrige los datos observados y emite un comprobante nuevo (con el siguiente correlativo). |
failed |
No se pudo entregar a SUNAT por credenciales SOL o configuración del emisor. | Pendiente de recepción en SUNAT. | No emitas otro comprobante. Una vez corregida la causa, reenvíalo con POST /v1/documents/{id}/retry. |
Ver el ciclo completo en Estados y envío a SUNAT.
Cómo solicitar soporte técnico
Sección titulada «Cómo solicitar soporte técnico»Para que podamos diagnosticar y resolver cualquier consulta con rapidez, incluye estos datos al contactar a soporte:
- Entorno: indica si ocurrió en Pruebas (
faktura-test.cgallardo.me) o en Producción (faktura.cgallardo.me). - Empresa: el RUC de la empresa emisora y el prefijo de la API key utilizada (p. ej.
sk_test_ec829766c02e, nunca el secreto completo). - Identificador: el
iddel comprobante o el valor de la cabeceraX-Request-Id(traceId) devuelto por la API. - Petición y respuesta: el método y ruta llamados (p. ej.
POST /v1/invoices), el cuerpo JSON enviado (payload) y el código HTTP + cuerpo JSON recibido.
Reglas de validación más comunes en details
Sección titulada «Reglas de validación más comunes en details»| Regla | Significado |
|---|---|
Required |
Campo obligatorio ausente. |
In |
Valor fuera de la lista permitida (ver Catálogos). |
Decimal |
No es un decimal válido o tiene más decimales de los permitidos. |
Gt, Lt |
Debe ser mayor que cero (Gt) o menor que el tope permitido (Lt, p. ej. porcentajes menores a 100). |
Max, Min, Size |
Excede la longitud o cantidad máxima (Max), no alcanza la mínima (Min) o no tiene la longitud exacta exigida (Size, p. ej. reason_code de 2 caracteres o detraction.code de 3). |
Regex |
No cumple el patrón del campo (p. ej. unit_code de 1 a 3 caracteres A-Z0-9 o sunat_product_code de 8 dígitos). |
Boolean |
Debe ser true o false. |
DateFormat, AfterOrEqual |
Fecha que no está en formato YYYY-MM-DD, o fecha to anterior a from. |
Email |
Dirección de correo electrónico con formato inválido (en to.*). |
RequiredIf, RequiredWith |
Obligatorio por el valor de otro campo (por ejemplo, installments con payment.type = credito). |
AmountOrPercent |
Un descuento o recargo debe llevar amount o percent, uno solo. |