---
name: faktura-limite-de-peticiones
description: "Límite de peticiones con la API de Faktura (facturación electrónica SUNAT, Perú). Cada API key puede hacer hasta 120 peticiones por minuto. El límite se cuenta por clave: dos sistemas con claves distintas no se restan entre sí. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Límite de peticiones — Faktura API

## Propósito

Le da a tu asistente el contexto para **límite de peticiones** con la API de Faktura: Cada API key puede hacer hasta 120 peticiones por minuto. El límite se cuenta por clave: dos sistemas con claves distintas no se restan entre sí.

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

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

## Cabeceras

Cada respuesta de `/v1` informa el límite y lo que te queda en el minuto en curso:

| Cabecera | Descripción |
| --- | --- |
| `X-RateLimit-Limit` | Peticiones por minuto de tu clave (`120`). |
| `X-RateLimit-Remaining` | Peticiones que te quedan en este minuto. |

## Al superar el límite

La API responde `429 Too Many Requests` con la cabecera `Retry-After`, que indica los **segundos** que debes esperar antes de volver a intentar:

```json
{ "reason": "TooManyRequests" }
```

Los enlaces públicos del PDF (`links.public_pdf`, `links.public_ticket` y `links.public_ticket_58`) no descuentan del límite de tu API key: tienen su propio límite de 60 descargas por minuto.

## Cómo no llegar al límite

- **Respeta `Retry-After`** y reintenta después de ese tiempo, no en un bucle inmediato.
- **Usa [webhooks](https://faktura-doc.cgallardo.me/webhooks/)** para saber cuándo SUNAT responde, en lugar de consultar cada comprobante una y otra vez. Si consultas, espera entre intentos como indica [Estados y envío](https://faktura-doc.cgallardo.me/estados-y-envio/).
- **Consulta RUC en lote**: [hasta 1000 por llamada](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc-lote/) cuentan como una sola petición.
- **Reintenta una emisión con la misma `Idempotency-Key`** ([Idempotencia](https://faktura-doc.cgallardo.me/idempotencia/)): no duplica el comprobante.

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