Guías › Integración
Errores y límites
Códigos de estado, formato de los errores, créditos, idioma de los mensajes y límites de la API.
Formato de los errores#
Cuando algo sale mal, la API responde con un estado HTTP de error y un JSON con el mensaje en error:
{ "error": "Agente no encontrado." }Algunos errores también tienen un code estable. Usa el code (y no el texto) para decidir qué hacer:
code | Estado | Significado |
|---|---|---|
no_credits | 402 | La organización se quedó sin créditos. Un administrador necesita agregar más en Configuración › Uso y créditos. |
plan_required | 402 | La organización todavía no tiene plan: solo el primer diagnóstico es gratis. El dueño elige el plan en Configuración › Plan y facturación. |
agent_budget | 402 | El agente alcanzó el presupuesto del mes. Su responsable puede aumentar el límite en la configuración del agente; si no, vuelve cuando cambie el mes. |
no_provider | 400 o 409 | No hay un modelo de IA disponible para ti. |
model_unavailable | 400 | El modelo pedido no está en el catálogo o no está habilitado para ti. |
provider_error | 502 | El proveedor del modelo falló. Vuelve a intentarlo. |
Códigos de estado#
| Estado | Cuándo ocurre |
|---|---|
200 / 201 | Funcionó. 201 cuando se creó algo. |
202 | Aceptado y en ejecución en segundo plano (webhooks y triggers/{id}/run). |
400 | Cuerpo no válido: falta un campo, tamaño fuera del límite, JSON mal formado. El mensaje dice qué campo. |
401 | Sin clave, o clave no válida o revocada. |
402 | Sin créditos (no_credits), sin plan (plan_required) o el agente agotó su presupuesto del mes (agent_budget). |
403 | Ves el elemento pero no puedes cambiarlo, o la acción solo funciona en el navegador. |
404 | El elemento no existe o no tienes acceso a él. La API no distingue los dos casos, para no revelar qué existe. |
409 | Conflicto de estado: la conversación ya se está ejecutando, el disparador está desactivado o hay que volver a conectar el conector. |
413 | Archivo demasiado grande (el Brain acepta hasta 20 MB por archivo). |
422 | El archivo o el texto llegó, pero no se pudo usar: formato no compatible, PDF sin texto, frase que no se puede convertir en un horario. |
5xx | Falla del servidor o del proveedor de IA. Vuelve a intentarlo con espera creciente. |
Errores durante el streaming#
Las rutas que responden en streaming (conversación con un agente y chat directo con un modelo) ya empezaron a responder con 200 cuando aparece el problema. En esos casos, el error llega como un evento en medio del flujo:
{"type":"error","message":"La organización se quedó sin créditos."}
{"type":"done","status":"failed"}Maneja siempre el evento error y el done con status: "failed". Los detalles están en Conversaciones y Chat.
Créditos#
Cuando la organización usa los modelos de la plataforma, cada respuesta consume créditos según el costo del modelo. El consumo desde la API y la CLI sale del mismo saldo que la app.
- Antes de un uso grande, consulta el saldo con
GET /api/creditsodoublex credits. - Sin saldo, el chat directo y la conversión de texto en horario responden
402 no_credits. La conversación con un agente responde con el eventoerroren el streaming. - Una conversación cancelada o que falló a mitad de camino también cobra lo que ya se procesó.
Idioma de los mensajes#
Los mensajes de error salen en el idioma de la persona dueña de la clave (uno de los 14 de la app, como Português, English, Español, Français o 日本語), el mismo que eligió en la app. Para cambiarlo por la API, usa PATCH /api/me con {"language": "en"}. Si la persona todavía no eligió un idioma, se usa el encabezado Accept-Language de la solicitud y, sin él, el idioma predeterminado de la organización.
Los mensajes de validación de formato (por ejemplo, name: Too small) pueden salir en inglés.
Límites#
| Qué | Límite |
|---|---|
| Mensaje para un agente | 100.000 caracteres |
| Tiempo de una respuesta de agente | 800 segundos por mensaje |
| Conversaciones al mismo tiempo | Una respuesta por conversación. Para ejecutar en paralelo, usa conversaciones distintas. |
| Archivo en el Brain | 20 MB por archivo; el texto por encima de 2 millones de caracteres se divide en partes |
| Archivo descargado de Creaciones | 2 MB |
| Resultado de herramienta de conector | 20.000 caracteres |
| Disparador programado | Como mínimo, cada 5 minutos |
| Cuerpo de webhook | 200.000 caracteres |
No hay límite de solicitudes por minuto, pero usa el sentido común: prefiere pocas llamadas grandes a muchas pequeñas y no hagas barridos en bucle.
Listas y paginación#
Las listas (GET /api/agents, GET /api/tasks, GET /api/skills, etc.) devuelven todo lo que puedes ver, sin paginación. Filtra en tu código o usa los filtros de cada ruta.