API · EMPEZAR

Errores, límites y créditos

Todo lo que puede decir que no, con el texto que devuelve. Con esto, tu cliente sabe qué reintentar y qué no.

La forma de un error

SIEMPRE

{"detail": "Sin acceso a este espacio."}

Con dos excepciones: la validación de la entrada (422) devuelve una lista en detail, y los 402 devuelven un objeto:

402 · CUENTA NO AL DÍA

{"detail": {"mensaje": "La cuenta de este espacio no está al día.",
            "motivo": "pago_vencido",
            "pagado_hasta": "2026-09-01"}}

402 · CRÉDITOS AGOTADOS

{"detail": {"mensaje": "La cuenta de este espacio agotó sus créditos de este ciclo.",
            "motivo": "bolsa_agotada",
            "creditos": {"incluidos": 800, "gastados": "800.0000", "restantes": "0.0000"},
            "renueva": "2026-10-15"}}

motivo puede ser pago_vencido, suspension_comercial o bolsa_agotada.

Qué puede decir que no

Para una ruta de un espacio llamada con una clave:

STATUS	SI	DETAIL
401	Sin clave	`No autenticado.`
401	Clave inexistente, mal formada o revocada	`Credencial de servicio inválida o revocada.`
429	Más de 120 peticiones por minuto con esta clave	`Demasiadas peticiones con esta credencial.`
403	Espacio fuera del alcance de la clave	`Sin acceso a este espacio.`
403	La prueba del espacio venció	`La prueba de este espacio ha finalizado.`
402	La cuenta no está al día	`objeto (abajo)`
403	La API del espacio está apagada	`La API de este espacio está apagada.`
403	Tu IP no está en la lista	`Esta dirección IP no está autorizada en este espacio.`
429	El espacio agotó su cuota diaria	`Este espacio agotó su cuota diaria de la API.`
429	Demasiadas peticiones por segundo en el espacio	`Demasiadas peticiones por segundo en este espacio.`
403	Ruta de escritura con una clave lee	`Tu cuenta es de solo lectura en este espacio.`
403	Ruta de un módulo que el espacio no tiene	`módulo no habilitado para este espacio.`
402	Créditos agotados (preguntar, subir y los módulos)	`objeto (abajo)`

Las validaciones de cada ruta (400, 404, 413, 422) están en su ficha. Una petición rechazada por API apagada o por IP no cuenta para tus límites.

Otros códigos

STATUS	CUÁNDO
404	La ruta no existe. Si llamas a `/api/rag/{espacio}` a secas, el `detail` te dice qué ruta usar.
405	Método equivocado en una ruta que existe. Trae la cabecera `Allow` con los métodos válidos.
413	Subida demasiado grande: ver load_documents.
429 · 503	El servicio está saturado en ese momento. Llegan sin `Retry-After`: espera unos segundos y reintenta con espera creciente.
502	El servicio no está disponible en ese momento o la pregunta pasó de 90 s. No es tu clave: reintenta con espera creciente.

Límites

LÍMITE	VALOR	DÓNDE SE CAMBIA
Por clave	120 peticiones en cualquier ventana de 60 s (deslizante)	Fijo
Por espacio y clave: tasa	2 por segundo (1 – 1000)	api-config · `solicitudes_por_segundo`
Por espacio y clave: ráfaga	120 seguidas (1 – 5000)	api-config · `rafaga`
Por espacio: cuota diaria	Sin tope (o 100 – 100 000 000), se reinicia a las 00:00 UTC	api-config · `cuota_diaria`

Los 429 de estos límites traen Retry-After en segundos. El de la cuota diaria apunta a la medianoche UTC.

Qué reintentar

429: espera lo que diga Retry-After y reintenta. Si no lo trae, espera unos segundos y dobla la espera en cada intento.
502 y 503: reintenta con espera creciente, dos o tres veces.
401, 402, 403, 404, 422: no reintentes. Algo hay que cambiar: la clave, el pago, la configuración o la petición.
200 con status_code "1001": no es un error de transporte. Reintentar la misma pregunta dará lo mismo.

Créditos

Gastan créditos las preguntas, la indexación de documentos y lo que hacen los módulos: armar una ficha de Fuentes o lanzar una fuente, y crear, refinar, validar o completar una landing.
Sin créditos se cortan con 402 conversations, conversations/stream, load_documents y las rutas de los módulos que crean o lanzan algo. Leer, listar, configurar y consultar la bolsa siguen funcionando.
El saldo, en la bolsa de créditos.

Tiempos

Una pregunta tarda de 2 a 20 s. Pon el timeout de tu cliente en 60 s o más.
Una pregunta que pase de 90 s se corta con 502.
En el stream, si no hay datos durante 15 s llega un : keepalive para que la conexión no se corte.