Límites de uso y errores
Disponible enProResearch
La API limita cuántas solicitudes pueden hacer una clave y una cuenta, y responde a cada rechazo con un código de estado y un código de error estable. Lee el código, no el texto del mensaje: el código no cambia.
Límites
Dos límites se aplican a cada llamada que usa una clave:
- Por clave, por hora. Cada clave tiene su propio límite por hora, con el máximo de tu plan como tope.
- Por cuenta, por día. Todas tus llamadas REST comparten un presupuesto diario. El día es UTC y se reinicia a las 00:00 UTC.
Las cifras de cada plan están en la tabla de Claves, permisos y límites. Algunas
rutas tienen un límite extra breve por minuto: hacer una pregunta (POST /ask) y empezar o terminar
una subida permiten un número limitado de llamadas por minuto.
Cabeceras
Cada respuesta a una llamada que pasó la comprobación por hora lleva:
X-RateLimit-Limit: el límite vigente para esta clave.X-RateLimit-Remaining: llamadas que quedan en la hora actual.
Cuando superas un límite, la respuesta es 429 con Retry-After, el número de segundos que hay que
esperar.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
Retry-After: 1260
Reintentar con educación
Espera Retry-After segundos y vuelve a intentarlo. No reintentes de inmediato en un bucle. Un script
que hace muchas llamadas debe parar cuando se alcanza el límite diario y continuar al día siguiente. El
ejemplo de Ejemplos muestra una función de solicitud que lo hace.
GET /rest/v2/usage te dice cuánto del día has usado.
La forma del error
Cada rechazo usa una única forma JSON. success es false y error contiene los detalles.
{
"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 es la parte legible por máquinas. Puede faltar en las respuestas simples de validación o de no
encontrado, donde statusCode y message llevan el significado. message puede ser una lista de
cadenas cuando varios campos son incorrectos.
Códigos de estado y de error
| Estado | Código | Significado |
|---|---|---|
| 400 | - | La solicitud está mal formada. Un parámetro de consulta o un campo del cuerpo que la ruta no conoce también da un 400. |
| 400 | SCOPE_NOT_ALLOWED | Pediste un permiso que tu plan no incluye al crear una clave. |
| 401 | API_KEY_INVALID | La clave falta, es desconocida, está revocada, ha caducado o está bloqueada. La respuesta lleva WWW-Authenticate: Bearer realm="readsira". |
| 401 | API_KEY_IN_QUERY | La clave se envió en la dirección. Envíala en una cabecera. |
| 402 | PLAN_REQUIRED | El plan no tiene API REST (Free), o no tiene subidas. Las claves MCP siguen funcionando en /mcp. |
| 402 | PLAN_LIMIT_REACHED | Se alcanzó un límite de recuento, por ejemplo las respuestas al mes. |
| 402 | AI_QUOTA_EXCEEDED | Se agotó el presupuesto de IA de este mes (POST /ask). |
| 402 | PROJECT_LIMIT_REACHED | Un proyecto está en el límite de elementos de tu plan. |
| 403 | SCOPE_REQUIRED | La clave no tiene el permiso que necesita la ruta. error.details.scopes lo nombra. |
| 404 | - | No encontrado, o no es tuyo. La API no dice cuál de los dos. |
| 409 | PROJECT_ARCHIVED | Intentaste escribir en un proyecto archivado. |
| 429 | RATE_LIMITED | El límite por hora o por día. error.details tiene window (hour o day), limit y retryAfterSeconds. |
| 503 | AI_PAUSED | La IA está en pausa durante el día (solo POST /ask). La búsqueda sigue funcionando. |
Un 429 sin código viene del límite breve por minuto de una ruta. Espera y reintenta del mismo modo.
Límites de las entradas
La API comprueba cada entrada y rechaza toda la solicitud con 400 cuando una está fuera de rango.
| Ruta | Entrada | Permitido |
|---|---|---|
GET /search | q | de 1 a 500 caracteres |
GET /search | limit | de 1 a 20, por defecto 8 |
POST /ask | question | de 1 a 2000 caracteres |
POST /ask | bookmarkIds | de 1 a 50 ids |
GET /documents/:id | offset | 0 o más caracteres |
GET /documents/:id | maxChars | de 1 a 20 000, por defecto 12 000 |
GET /documents/:id/chunks | limit | de 1 a 100, por defecto 20 |
GET /documents/:id/transcript | limit | de 1 a 500 |
GET /projects | limit | de 1 a 50, por defecto 20 |
GET /projects/:id/context | q | de 1 a 500 caracteres |
GET /projects/:id/context | maxChars | de 1 a 32 000, por defecto 16 000 |
Cada ruta tiene una lista completa con los tipos en la referencia de la API REST v2.