Rate Limits

Cada respuesta de la API v2 incluye tres headers que te dicen cuántas llamadas te quedan antes de alcanzar tu límite. No tienes que esperar un error para saberlo.

Headers en cada respuesta

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1745018460

Header	Tipo	Descripción
`X-RateLimit-Limit`	`integer`	Máximo de requests permitidos por minuto para tu API key.
`X-RateLimit-Remaining`	`integer`	Requests que te quedan en la ventana actual.
`X-RateLimit-Reset`	`integer`	Unix timestamp (segundos) en que la ventana se reinicia.
`X-RateLimit-Reason`	`string`	Solo en 429: razón del límite alcanzado (ver tabla abajo).

X-RateLimit-Reset es un Unix timestamp absoluto, no un conteo de segundos. Conviértelo con new Date(reset * 1000) en JavaScript.

Headers de diagnóstico

Además de los headers de rate limit, cada respuesta de la API v2 incluye dos headers de diagnóstico útiles para depuración:

X-Allsign-Request-Id: req_4a3f2b1c8e7d6f5a
X-Allsign-Environment: dev

Header	Descripción
`X-Allsign-Request-Id`	ID único del request, generado por el servidor. Empieza con `req_`. Inclúyelo al reportar un problema al soporte.
`X-Allsign-Environment`	Ambiente de tu API key (`dev`, `test`, `live`). Solo aparece en requests autenticados con una API key v2.

X-Allsign-Request-Id aparece en todos los requests, incluyendo los que devuelven un 429. Esto te permite rastrear exactamente qué request fue rechazado.

Scopes en cada respuesta

Cada respuesta de la API v2 incluye dos headers que muestran los permisos del request — incluso en respuestas exitosas y en errores 403:

X-Accepted-Scopes: document:write, document:*
X-Your-Scopes: document:read, analytics:read

Header	Descripción
`X-Accepted-Scopes`	Los scopes que el endpoint acepta. Aparece en todas las respuestas del endpoint, incluyendo 403.
`X-Your-Scopes`	Los scopes que tiene tu API key. Aparece en cualquier request autenticado.

El caso de uso clave es el debugging de permisos. Cuando recibes un 403, no tienes que leer el body del error — los headers te dicen exactamente qué scope necesitas añadir:

# Respuesta 403
HTTP/1.1 403 Forbidden
X-Accepted-Scopes: document:write, document:*
X-Your-Scopes: document:read

# → Necesitas añadir document:write a tu API key

Esto es especialmente útil en herramientas como Postman o en logs de un SDK — ves el problema en la vista de headers sin tener que parsear JSON.

X-Accepted-Scopes refleja los scopes del endpoint específico que estás llamando, no todos los scopes posibles de la API. Un endpoint de lectura mostrará document:read, document:*; uno de creación mostrará document:write, document:*.

Límites por ambiente

El límite viene de tu plan de suscripción activo y aplica igual para todos los ambientes (dev, test, live) del mismo tenant.

Plan	Límite
Sin plan activo	10 req/min
Freemium	10 req/min
Esencial	100 req/min
Colabora	100 req/min
Conecta	100 req/min
Business	150 req/min

Si tu suscripción tiene un api_rpm_override acordado con nosotros, ese valor gana sobre el del plan.

Límites por endpoint

Algunos endpoints tienen un límite propio además del de tu plan, porque cada llamada cuesta bastante más que una request normal. Se cuentan por separado: consumir el de un endpoint no gasta el presupuesto de otro ni el de tu plan.

Endpoint	Límite	Por qué
`POST /v2/documents/{id}/invite-bulk`	10/min	Cada llamada se abre en un envío por participante.
`POST /v3/constancias`	20/min	Cada llamada es una emisión facturada ante el PSC.
`POST /v3/devassist/chat`	10/min	Cada turno dispara una llamada a un modelo de lenguaje.

El resto de los endpoints no tiene un límite propio por debajo del de tu plan: si tu plan dice 100 req/min, puedes crear documentos e invitar firmantes hasta ese número.

Un 429 de este tipo trae X-RateLimit-Reason: endpoint. Distínguelo del de tu plan (per-tenant) antes de asumir que necesitas otro paquete: si el header dice endpoint, subir de plan no lo resuelve.

Qué hacer con un 429

Cuando superas el límite recibirás un 429 Too Many Requests. El cuerpo incluye toda la información necesaria para hacer retry de forma inteligente:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Limit: 100 req/min.",
    "limit": 100,
    "remaining": 0,
    "reset": 1745018460,
    "retry_after": 23,
    "environment": "live"
  }
}

El header Retry-After también viene en la respuesta con el mismo valor en segundos:

Retry-After: 23

Patrón recomendado de retry

async function callWithRetry(fn: () => Promise<Response>): Promise<Response> {
  const resp = await fn()

  if (resp.status === 429) {
    const retryAfter = parseInt(resp.headers.get('Retry-After') ?? '60', 10)
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
    return fn() // un solo retry
  }

  return resp
}

Para integraciones de alto volumen, implementa exponential backoff con jitter en lugar de un retry único.

Campos del error 429

Todos los campos van anidados bajo error (envelope estándar de la API v2):

Campo	Tipo	Descripción
`error.code`	`string`	Siempre `RATE_LIMIT_EXCEEDED`.
`error.type`	`string`	Siempre `rate_limit_exceeded`.
`error.limit`	`integer`	Límite de tu key.
`error.remaining`	`integer`	Siempre `0` en un 429.
`error.reset`	`integer`	Unix timestamp de reinicio de ventana.
`error.retry_after`	`integer`	Segundos hasta que puedes reintentar.
`error.environment`	`string`	Ambiente de la key (`dev`, `test`, `live`).

Este es el 429 per-tenant (límite de tu plan). El 429 por límite de endpoint (X-RateLimit-Reason: endpoint) devuelve un body distinto: {"error":"Rate limit exceeded","message":...,"retry_after":...} sin campo code. El 429 diario por IP (requests sin API key) es el único que incluye upgrade_message.

X-RateLimit-Reason

El header X-RateLimit-Reason indica qué tipo de límite fue el que se superó:

Valor	Descripción
`per-tenant`	Límite determinado por tu plan de suscripción. El más común.
`endpoint`	Límite propio de ese endpoint — ver Límites por endpoint. Subir de plan NO lo cambia.
`daily-ip`	Límite diario por IP para requests sin API key válida.

Embedded Signing

Los endpoints de Embedded Signing tienen límites adicionales independientes del límite global. Cuando los excedes recibirás también headers específicos:

X-Embedded-RateLimit-Limit-Minute: 30
X-Embedded-RateLimit-Remaining-Minute: 0
X-Embedded-RateLimit-Reset-Minute: 1745018460
X-Embedded-RateLimit-Limit-Day: 1000
X-Embedded-RateLimit-Remaining-Day: 847
X-Embedded-RateLimit-Reset-Day: 1745104860

Los error_code para estos 429 son EMBEDDED_RATE_LIMIT_MINUTE y EMBEDDED_RATE_LIMIT_DAY. Consulta la guía de Embedded Signing para más detalle.