Skip to main content

Codigos HTTP

StatusSignificadoCausa comun
200OKPeticion exitosa
400Bad RequestParametros faltantes o invalidos
401UnauthorizedAPI Key no proporcionada o invalida
403ForbiddenFeature no disponible en tu plan
429Too Many RequestsRate limit alcanzado
500Internal ErrorError del servidor

Error 401: API Key invalida

{
  "statusCode": 401,
  "message": "Invalid API key"
}
Solucion: Verifica que el header X-API-Key tenga una key valida y activa. Puedes crear una nueva en la plataforma.

Error 403: Feature no disponible

{
  "statusCode": 403,
  "message": "Feature not available in your plan",
  "currentPlan": "STARTER",
  "requiredFeatures": ["mcp_servers"]
}
Solucion: Algunas features solo estan disponibles en planes superiores. Revisa los planes o contacta ventas para un upgrade.

Error 429: Rate limit

{
  "statusCode": 429,
  "message": "Rate limit exceeded"
}
El header Retry-After indica cuantos segundos esperar antes de reintentar:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Limites por plan:
PlanRequests/min
Starter5
Growth50
EnterpriseSin limite

Manejo recomendado

const response = await fetch(url, { headers });

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
  console.log(`Rate limit. Reintentando en ${retryAfter}s...`);
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // Reintentar
}

Errores en streaming (SSE)

Durante un stream, los errores se envian como eventos SSE:
event: error
data: {"message":"Error procesando la solicitud"}
El widget maneja estos errores automaticamente. Si usas la API directamente, escucha el evento error:
// Con fetch + ReadableStream
switch (eventType) {
  case 'error':
    const data = JSON.parse(rawData);
    console.error('Error del agente:', data.message);
    break;
}

Errores comunes

No se envio el header X-API-Key. Asegurate de incluirlo en todas las peticiones.
La API Key no corresponde a ningun tenant activo. Verifica que no este revocada y que sea correcta.
Intentaste usar una feature que requiere un plan superior (ej: MCP Servers en plan Starter).
Excediste el limite de requests por minuto de tu plan. Espera el tiempo indicado en Retry-After.
El agente puede tardar mas si ejecuta multiples tools. El timeout default es de 60 segundos. Si usas tools HTTP lentas, considera optimizar tus endpoints.