Ir al contenido

Errores

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"]
}
  • reason es 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 forma campo:Regla, con la ruta del campo en notación de puntos (items.0.quantity es 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.

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.

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.
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.
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.

Para que podamos diagnosticar y resolver cualquier consulta con rapidez, incluye estos datos al contactar a soporte:

  1. Entorno: indica si ocurrió en Pruebas (faktura-test.cgallardo.me) o en Producción (faktura.cgallardo.me).
  2. Empresa: el RUC de la empresa emisora y el prefijo de la API key utilizada (p. ej. sk_test_ec829766c02e, nunca el secreto completo).
  3. Identificador: el id del comprobante o el valor de la cabecera X-Request-Id (traceId) devuelto por la API.
  4. 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.