Documentación
Límites de la API
Los límites de la API v1 son valores iniciales publicados en el contrato: cada respuesta limitada trae cabeceras RateLimit y, si hay que esperar, Retry-After; cambiarlos no rompe la API.
Límites de tasa
Estas cifras son valores iniciales publicados en el contrato. Se ajustan con la experiencia; cambiarlos no rompe la API.
Toda respuesta de una ruta limitada trae RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Un 429 trae además Retry-After. Los valores van por ventana; la ráfaga es lo que se permite de golpe sobre el ritmo sostenido.
| Límites de tasa | Ventana | Práctica | Real | Ráfaga |
|---|---|---|---|---|
| Toda petición autenticada, por llave | 1 min | 120 | 60 | 30 |
| Pedir pagos (`POST /v1/spends`), por agente | 1 min | 20 | 10 | 5 |
| Pedir pagos por día, por agente | 1 día | 1000 | 200 | 0 |
| Comprobar un pago (`POST /v1/spends/check`), por agente | 1 min | 60 | 30 | 10 |
| Escrituras de administración (agentes, reglas, destinos, llaves), por llave | 1 min | 30 | 15 | 10 |
| Rotar o crear llaves por día, por dueño | 1 día | 50 | 10 | 0 |
| Control del entorno de práctica (`/v1/test/*`), por dueño | 1 h | 120 | 0 | 20 |
| Peticiones con llave inválida o ausente, por IP | 10 min | 30 | 30 | 0 |
Cabeceras
Las cabeceras de límite que devuelve la API son:
RateLimit-LimitRateLimit-RemainingRateLimit-ResetRetry-After
Tamaños
Valores máximos de la petición y de algunos campos.
| Tamaños | Valor |
|---|---|
| Cuerpo de la petición | 16 KiB |
| `memo` | 280 caracteres |
| `client_reference` | 64 caracteres |
| `destination` | 253 caracteres |
| URL de `resource` | 2048 caracteres |
| Elementos por página (por defecto) | 10 elementos |
| Elementos por página (máximo) | 50 elementos |
| Espera larga (`wait_seconds`) | 20 segundos |
| Memoria de la llave de idempotencia (mínimo) | 24 horas |
| Vida de una aprobación pendiente (por defecto) | 15 minutos (5-60) |
| Ventana de aviso de compra duplicada | 60 segundos |
| Vida de una llave de práctica (por defecto) | 90 días |
| Vida de una llave real (por defecto) | 30 días |
| Convivencia al rotar una llave (máximo) | 7 días |
Cuotas
Topes de cuántas cosas puede tener cada dueño.
| Cuotas | Valor |
|---|---|
| Agentes activos en práctica | 5 |
| Agentes activos en real | 10 |
| Agentes archivados | 20 |
| Llaves activas por agente | 3 |
| Llaves de dueño activas | 3 |
| Destinos de webhook | 10 |
| Días que se guardan los eventos | 30 |
Idempotencia
- Con la misma llave y la misma huella (monto, moneda, destino y recurso), la API devuelve el estado actual del mismo pago con
idempotent_replay: true, sin pagar de nuevo. - El
memoy elclient_referenceno cuentan en la huella: un modelo los reescribe cada vez que reintenta. - La misma llave con una huella distinta da 409
idempotency_conflict;changed_fieldsdice qué cambió. - Un pago
faileddeja la llave gastada: un intento nuevo exige una llave nueva.
Webhooks
- Tiempo máximo de respuesta del destino: 5 segundos.
- Intentos por entrega: 8, en unas 24 horas.
- Tras 20 fallos seguidos el destino se pausa y se avisa al dueño.