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. El default sin plan activo es 100 req/min.

Configuración	Límite
Sin plan activo	100 req/min
Plan activo	Según `default_api_rpm` del plan
Override manual	Según `api_rpm_override` de la suscripción

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:

{
  "detail": {
    "error_code": "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

Campo	Tipo	Descripción
`error_code`	`string`	Siempre `RATE_LIMIT_EXCEEDED`.
`limit`	`integer`	Límite de tu key.
`remaining`	`integer`	Siempre `0` en un 429.
`reset`	`integer`	Unix timestamp de reinicio de ventana.
`retry_after`	`integer`	Segundos hasta que puedes reintentar.
`environment`	`string`	Ambiente de la key (`dev`, `test`, `live`).
`upgrade_message`	`string`	Solo en keys `dev`/`test` — cómo subir a `live`.

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 específico del endpoint (p.ej. bulk invitations tiene un límite más estricto).
`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.