Límits de freqüència i quotes

Dos tipus de límits mantenen l’API ràpida per a tothom:

• El límit de freqüència d’una clau: quantes sol·licituds per segon pot enviar, amb una ràfega per als pics curts.
• Les quotes de l’organització: quantes sol·licituds poden enviar entre totes les seves claus per minut, per dia i per mes.

Tots dos depenen del pla de l’organització. Cada resposta us indica en quin punt us trobeu, de manera que un client ben fet no ha d’endevinar mai res.

Límit de freqüència d’una clau

Cada clau té una freqüència constant i una ràfega. La ràfega us permet enviar aquest nombre de sol·licituds de cop; després, les sol·licituds s’admeten a la freqüència constant.

La classe depèn del pla de l’organització. GET /v1/me mostra la classe, la freqüència i la ràfega de la clau que el crida (rate_limit). El límit s’aplica a la clau en conjunt, independentment de quants servidors de l’API atenguin les vostres sol·licituds.

Els punts finals de transmissió en temps real, POST /v1/chat (amb "stream": true o sense) i GET /v1/jobs/stream, queden fora del límit de freqüència de la clau: no el consumeixen, i les seves capçaleres RateLimit no tenen cap element "key". Sí que compten per a les quotes de l’organització, una vegada cadascun, quan comença la sol·licitud. Les preguntes tenen límits propis, que es descriuen més avall.

Quotes de l’organització

Un pla pot fixar quotes de sol·licituds per a l’organització: per minut, per dia i per mes. Les finestres són períodes de calendari en UTC: un minut comença al segon :00, un dia a les 00:00 UTC i un mes el primer dia a les 00:00 UTC. Compta cada sol·licitud feta amb una clau o un token OAuth de l’organització, a qualsevol adreça. Una sol·licitud de transmissió en temps real compta una vegada, quan comença, duri el que duri; si la quota s’ha esgotat, es rebutja amb 429 com qualsevol altra sol·licitud. Una sol·licitud rebutjada amb 429 no compta.

Les capçaleres

Cada resposta a una sol·licitud feta amb una clau porta els límits que s’hi apliquen:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy i RateLimit segueixen l’esborrany de l’IETF RateLimit header fields for HTTP. Cada element és un límit:

X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset informen del més estricte d’aquests límits en una forma més simple, per als clients escrits abans que existís RateLimit. X-RateLimit-Reset és en segons.

Quan s’arriba a un límit

L’API respon 429 Too Many Requests amb una capçalera Retry-After en segons:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Espereu el temps de Retry-After i repetiu la sol·licitud. Repetiu POST i PATCH amb la mateixa Idempotency-Key. Les funcions auxiliars de reintent d’Errors fan totes dues coses.

Altres límits del pla també responen 429 amb Retry-After, per exemple el nombre de preguntes per dia (limits.questions) o de respostes en curs alhora (limits.concurrent_answers). Gestioneu-los de la mateixa manera.

Mantenir-se dins dels límits

• Llegiu RateLimit i aneu més a poc a poc quan r baixi, en lloc d’esperar un 429.
• Repartiu la feina massiva en el temps i feu servir els punts finals de lots on n’hi hagi: un lot de 100 documents és una sola sol·licitud.
• No consulteu si hi ha canvis en un bucle continu. Subscriviu-vos als webhooks o llegiu el canal d’esdeveniments cada pocs segons.
• Executeu els processos de treball en paral·lel amb un limitador compartit. Diversos processos amb una mateixa clau comparteixen un sol límit de freqüència.
• Si la vostra integració necessita més, pregunteu a la vostra persona de contacte a Sursa per una classe superior.