---
name: faktura-errores
description: "Errores con la API de Faktura (facturación electrónica SUNAT, Perú). Toda falla controlada responde con un código estable en reason y, a veces, una lista de details: Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Errores — Faktura API

## Propósito

Le da a tu asistente el contexto para **errores** con la API de Faktura: Toda falla controlada responde con un código estable en reason y, a veces, una lista de details:

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-errores/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/errores/

## Autenticación y cabeceras

- `Authorization: Bearer <api key>`. En pruebas, una clave `sk_test_` (SUNAT beta, sin valor tributario); en producción, la `sk_live_`. El ambiente lo decide la clave.
- `Content-Type: application/json` en las peticiones con cuerpo.
- `Idempotency-Key` (recomendada al emitir): repetir la petición con la misma clave y el mismo cuerpo devuelve el mismo comprobante, sin duplicarlo.
- Errores: JSON `{ "reason": "<código>", "details": [...] }`. `401` clave inválida o vencida, `403` alcance insuficiente, `422` datos inválidos, `429` límite de 120 peticiones por minuto (respeta `Retry-After`), `500` solo con `traceId`.

## Formato

Toda falla controlada responde con un código estable en `reason` y, a veces, una lista de `details`:

```json
{
  "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:

```json
{ "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

| Estado | `reason` | Qué hacer |
| --- | --- | --- |
| `400` | `BadRequest` | Revisa que el cuerpo sea JSON válido. |
| `401` | `Unauthenticated` | Revisa tu API key ([Autenticación](https://faktura-doc.cgallardo.me/autenticacion/)). |
| `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](https://faktura-doc.cgallardo.me/limite-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`)

| 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](https://faktura-doc.cgallardo.me/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

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

| 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

| 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

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](https://faktura-doc.cgallardo.me/webhooks/) o en [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/)). 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`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/reintentar/). |

Ver el ciclo completo en [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

## Cómo solicitar soporte técnico

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`

| Regla | Significado |
| --- | --- |
| `Required` | Campo obligatorio ausente. |
| `In` | Valor fuera de la lista permitida (ver [Catálogos](https://faktura-doc.cgallardo.me/catalogos/)). |
| `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. |

## Reglas generales de la API

- Montos en las respuestas como texto decimal (`"16.00"`); en las peticiones, número o texto.
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`); identificadores UUID.
- Un comprobante emitido responde `201` con `status: "pending"`: el número ya es tuyo. El resultado de SUNAT llega después (webhook o `GET /v1/documents/{id}`).
- Documentación completa: https://faktura-doc.cgallardo.me/ · Toda la API en una skill: https://faktura-doc.cgallardo.me/skills/faktura-api.md
