Límites de solicitudes API: encabezados y backoff 429

​

Identificador y exenciones

1. Encabezado x-api-key → contador por clave.
2. Primer salto de X-Forwarded-For → contador por IP.
3. REMOTE_ADDR → contador por IP.

• La clave interna DIDIT_WEBAPP_API_KEY (la usa únicamente la consola de Didit).
• Los endpoints protegidos por el permiso IsValidSession (el tráfico de sesiones integradas o del SDK).
• GET /system/healthcheck (lo atiende HealthMiddleware antes de esta capa).
• Los webhooks de proveedores: Stripe, análisis AML, callbacks de verificación facial y modificación de listas KYC.

​

Límites globales

​

Límites específicos por endpoint

​

Formato de la respuesta 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1762534870
Retry-After: 37

{
  "detail": "Session creation rate limit exceeded. You can make up to 600 requests per minute."
}

​

Recomendaciones para el cliente

• Respeta Retry-After como valor mínimo de tu espera. Por encima de él, aplica un backoff exponencial con jitter (5s → 10s → 20s → 40s ± random) para que dos clientes que reciben 429 al mismo tiempo no se sincronicen.
• Deja de reintentar tras un número reducido de intentos (por ejemplo, 5). Devuelve el error a quien hizo la llamada y avisa a tu equipo: los 429 sostenidos suelen indicar un bucle descontrolado, no un pico pasajero.
• Usa un identificador por cada carga de trabajo. Compartir una x-api-key entre muchos backends los agrupa en el mismo contador, lo que puede hacer que un vecino ruidoso deje sin capacidad al resto. Crea una aplicación independiente (y, por tanto, una api_key independiente) por entorno, marca o cliente: consulta Registro programático.
• Almacena en caché las lecturas de decisiones. Los endpoints /decision/ no están pensados para bucles de sondeo intensivos; si necesitas actualizaciones en tiempo real, usa Webhooks y llama a GET /v3/session/<id>/decision/ solo para completar datos faltantes o para auditoría.
• Genera los PDF de forma diferida. La generación de PDF consume mucha CPU (límite de 50/min). Lánzala desde una cola cuando la sesión alcance un estado terminal, no en cada visualización de página.

​

Ejemplo de cliente que gestiona el 429

async function postSession(body) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch("https://verification.didit.me/v3/session/", {
      method: "POST",
      headers: {
        "x-api-key": process.env.DIDIT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (res.status !== 429) return res;

    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("Didit: too many 429s, giving up");
}

import os
import random
import time

import httpx

def post_session(body: dict) -> httpx.Response:
    with httpx.Client(timeout=15) as client:
        for _ in range(5):
            resp = client.post(
                "https://verification.didit.me/v3/session/",
                headers={
                    "x-api-key": os.environ["DIDIT_API_KEY"],
                    "Content-Type": "application/json",
                },
                json=body,
            )
            if resp.status_code != 429:
                return resp
            wait_s = float(resp.headers.get("Retry-After", "1")) + random.random()
            time.sleep(wait_s)
    raise RuntimeError("Didit: too many 429s, giving up")

​

Cómo obtener más margen