Limite de requisições da API: cabeçalhos e backoff 429

​

Identificador e isenções

1. Cabeçalho x-api-key → contador por chave.
2. Primeiro salto de X-Forwarded-For → contador por IP.
3. REMOTE_ADDR → contador por IP.

• A DIDIT_WEBAPP_API_KEY interna (usada apenas pelo console da Didit).
• Endpoints protegidos pela permissão IsValidSession (o tráfego de sessões incorporadas e de SDK).
• GET /system/healthcheck (atendido pelo HealthMiddleware antes desta pilha).
• Webhooks de provedores: Stripe, análise AML, callbacks de verificação facial e alterações de listas de KYC.

​

Limites globais

​

Limites específicos por endpoint

​

Formato da resposta 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."
}

​

Orientações para o cliente

• Respeite o Retry-After como o valor mínimo para o backoff. Sobre ele, aplique um backoff exponencial com jitter (5s → 10s → 20s → 40s ± random) para que dois clientes que recebam 429 ao mesmo tempo não se sincronizem.
• Pare de tentar novamente após um limite baixo (por exemplo, 5 tentativas). Repasse o erro a seu chamador e alerte sua equipe: 429s persistentes geralmente indicam um loop descontrolado, não um pico passageiro.
• Use um identificador por carga de trabalho. Compartilhar uma x-api-key entre vários backends coloca todos no mesmo contador, o que pode fazer com que uma aplicação que consome muitos recursos esgote a capacidade dos demais. Crie uma aplicação separada (e, portanto, uma api_key separada) por ambiente, marca ou cliente. Consulte Registro programático.
• Armazene em cache as leituras de decisão. Os endpoints /decision/ não foram projetados para loops de polling intensos; se você precisa de atualizações em tempo real, use Webhooks e chame GET /v3/session/<id>/decision/ apenas para preenchimento retroativo ou auditoria.
• Gere PDFs de forma assíncrona. A renderização de PDF consome muita CPU (teto de 50/min). Dispare-a a partir de uma fila depois que a sessão atingir um status final, e não a cada visualização de página.

​

Exemplo de cliente que trata 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")

​

Precisa de mais capacidade?