Limites de débit et erreurs
Disponible avecProResearch
L'API limite le nombre de requêtes qu'une clé et un compte peuvent effectuer, et répond à chaque refus avec un code de statut et un code d'erreur stable. Lisez le code, pas le texte du message : le code ne change pas.
Limites
Deux limites s'appliquent à chaque appel qui utilise une clé :
- Par clé, par heure. Chaque clé a sa propre limite horaire, plafonnée au maximum de votre offre.
- Par compte, par jour. Tous vos appels REST partagent un budget quotidien. La journée est en UTC et se réinitialise à 00:00 UTC.
Les chiffres de chaque offre figurent dans le tableau de Clés, portées et limites.
Quelques routes ont une courte limite supplémentaire par minute : poser une question (POST /ask)
et démarrer ou terminer un import autorisent un nombre limité d'appels par minute.
En-têtes
Chaque réponse à un appel qui a passé le contrôle horaire contient :
X-RateLimit-Limit: la limite en vigueur pour cette clé.X-RateLimit-Remaining: les appels restants dans l'heure en cours.
Quand vous dépassez une limite, la réponse est 429 avec Retry-After, le nombre de secondes à
attendre.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
Retry-After: 1260
Réessayer poliment
Attendez Retry-After secondes puis réessayez. Ne réessayez pas immédiatement en boucle. Un script
qui effectue de nombreux appels doit s'arrêter quand la limite quotidienne est atteinte et
reprendre le lendemain. L'exemple de Exemples montre une fonction de requête qui
fait cela.
GET /rest/v2/usage indique la part de la journée que vous avez utilisée.
La forme de l'erreur
Chaque refus utilise une seule forme JSON. success vaut false, et error contient les détails.
{
"success": false,
"error": {
"statusCode": 403,
"message": "This API key lacks the scope read:library.",
"code": "SCOPE_REQUIRED",
"details": { "scopes": ["read:library"] },
"timestamp": "2026-11-04T09:00:00.000Z",
"path": "/rest/v2/search",
"method": "GET"
}
}
code est la partie lisible par une machine. Il peut manquer dans les simples réponses de
validation ou d'introuvable, où statusCode et message portent le sens. message peut être une
liste de chaînes quand plusieurs champs sont erronés.
Statuts et codes d'erreur
| Statut | Code | Signification |
|---|---|---|
| 400 | - | La requête est mal formée. Un paramètre de requête ou un champ de corps que la route ne connaît pas est aussi un 400. |
| 400 | SCOPE_NOT_ALLOWED | Vous avez demandé, en créant une clé, une portée que votre offre n'inclut pas. |
| 401 | API_KEY_INVALID | La clé est absente, inconnue, révoquée, expirée ou bloquée. La réponse contient WWW-Authenticate: Bearer realm="readsira". |
| 401 | API_KEY_IN_QUERY | La clé a été envoyée dans l'adresse. Envoyez-la dans un en-tête. |
| 402 | PLAN_REQUIRED | L'offre n'a pas d'API REST (Free), ou pas d'imports. Les clés MCP fonctionnent toujours avec /mcp. |
| 402 | PLAN_LIMIT_REACHED | Une limite de quantité est atteinte, par exemple les réponses par mois. |
| 402 | AI_QUOTA_EXCEEDED | Le budget d'IA de ce mois est épuisé (POST /ask). |
| 402 | PROJECT_LIMIT_REACHED | Un projet a atteint la limite d'éléments de votre offre. |
| 403 | SCOPE_REQUIRED | La clé n'a pas la portée dont la route a besoin. error.details.scopes la nomme. |
| 404 | - | Introuvable, ou pas à vous. L'API ne dit pas lequel. |
| 409 | PROJECT_ARCHIVED | Vous avez essayé d'écrire dans un projet archivé. |
| 429 | RATE_LIMITED | La limite horaire ou quotidienne. error.details contient window (hour ou day), limit et retryAfterSeconds. |
| 503 | AI_PAUSED | L'IA est en pause pour la journée (POST /ask uniquement). La recherche continue de fonctionner. |
Un 429 sans code provient de la courte limite par minute d'une route. Attendez et réessayez de la
même façon.
Limites des entrées
L'API vérifie chaque entrée et refuse toute la requête avec 400 quand l'une est hors limites.
| Route | Entrée | Valeurs autorisées |
|---|---|---|
GET /search | q | 1 à 500 caractères |
GET /search | limit | 1 à 20, 8 par défaut |
POST /ask | question | 1 à 2000 caractères |
POST /ask | bookmarkIds | 1 à 50 identifiants |
GET /documents/:id | offset | 0 caractère ou plus |
GET /documents/:id | maxChars | 1 à 20 000, 12 000 par défaut |
GET /documents/:id/chunks | limit | 1 à 100, 20 par défaut |
GET /documents/:id/transcript | limit | 1 à 500 |
GET /projects | limit | 1 à 50, 20 par défaut |
GET /projects/:id/context | q | 1 à 500 caractères |
GET /projects/:id/context | maxChars | 1 à 32 000, 16 000 par défaut |
Chaque route a une liste complète avec les types dans la référence de l'API REST v2.