DoubleX AgentesDocs

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:

JSON
{ "error": "Agente no encontrado." }

Algunos errores también tienen un code estable. Usa el code (y no el texto) para decidir qué hacer:

codeEstadoSignificado
no_credits402La organización se quedó sin créditos. Un administrador necesita agregar más en Configuración › Uso y créditos.
plan_required402La 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_budget402El 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_provider400 o 409No hay un modelo de IA disponible para ti.
model_unavailable400El modelo pedido no está en el catálogo o no está habilitado para ti.
provider_error502El proveedor del modelo falló. Vuelve a intentarlo.

Códigos de estado#

EstadoCuándo ocurre
200 / 201Funcionó. 201 cuando se creó algo.
202Aceptado y en ejecución en segundo plano (webhooks y triggers/{id}/run).
400Cuerpo no válido: falta un campo, tamaño fuera del límite, JSON mal formado. El mensaje dice qué campo.
401Sin clave, o clave no válida o revocada.
402Sin créditos (no_credits), sin plan (plan_required) o el agente agotó su presupuesto del mes (agent_budget).
403Ves el elemento pero no puedes cambiarlo, o la acción solo funciona en el navegador.
404El elemento no existe o no tienes acceso a él. La API no distingue los dos casos, para no revelar qué existe.
409Conflicto de estado: la conversación ya se está ejecutando, el disparador está desactivado o hay que volver a conectar el conector.
413Archivo demasiado grande (el Brain acepta hasta 20 MB por archivo).
422El 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.
5xxFalla 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:

NDJSON
{"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/credits o doublex 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 evento error en 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 agente100.000 caracteres
Tiempo de una respuesta de agente800 segundos por mensaje
Conversaciones al mismo tiempoUna respuesta por conversación. Para ejecutar en paralelo, usa conversaciones distintas.
Archivo en el Brain20 MB por archivo; el texto por encima de 2 millones de caracteres se divide en partes
Archivo descargado de Creaciones2 MB
Resultado de herramienta de conector20.000 caracteres
Disparador programadoComo mínimo, cada 5 minutos
Cuerpo de webhook200.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.