Ir al contenido

Referencia y límites

Los rate limits están diferenciados por bucket. Cada bucket cuenta de forma independiente —el tráfico de lectura no consume cuota de escritura— y los contadores son por API Key. La excepción son las llamadas con token efímero (csk_eph_*), que se cuentan por dirección IP del cliente.

BucketLímiteEndpoints
write60 req/minPOST /channel/message · POST /channel/message/stream · POST /channel/outbound — envío de mensajes reales
read300 req/minGET /ping · GET /conversations/.../messages · GET /leads/...
sandbox600 req/minPOST /channel/message/sandbox — testing sin LLM

Endpoints especiales:

EndpointLímite
POST /channel/webhook-secret/rotate5 req/min
POST /channel/webhook-secret/confirm · /cancel10 req/min
POST /channel/webhooks/test30 req/min
POST · DELETE /channel/session-tokens60 req/min

Un 429 con este cuerpo:

{ "detail": "Too many requests. Please try again later." }
ConceptoValor
Tamaño de mensajeMáximo 5.000 caracteres
session_idMáximo 200 caracteres
contact_nameMáximo 120 caracteres (se recorta)
Idempotency-KeyMáximo 200 caracteres · TTL 24h en /channel/message
media_base64Unos 10 MB de archivo (14.000.000 de caracteres en base64); si se supera, 422
sample_payload de /webhooks/testMáximo 8 KB
Token efímero TTLDefault 30 min · máximo 4h
Rotación de webhookVentana dual: 72h
Timeout de webhook10 segundos para responder con un código 2xx
Entrega de webhook4 intentos en total: el inicial y reintentos a los 10 s, 30 s y 2 min
Versión soportadaX-Overtaker-Version: 1
API Keys activasMáximo 3 de Canal API por tenant (las del conector MCP se cuentan aparte)

POST /channel/message/sandbox simula /channel/message sin llamar al LLM, sin persistir mensajes ni leads, y sin consumir cuota del bucket write. Usa su propio bucket sandbox (600/min). Ideal para wizards de setup, CI/CD y para probar firma de webhooks sin gastar créditos.

POST /api/v1/channel/message/sandbox
Authorization: Bearer sk_live_YOUR_KEY
Content-Type: application/json
X-Overtaker-Version: 1
{ "session_id": "test-user", "message": "test" }
// 200 OK
{
"message_id": "sb_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "received"
}

Si la API key tiene webhook_url configurada, se dispara un webhook message.response canned con el marcador "sandbox": true para que tu handler procese un payload realista:

{
"event": "message.response",
"sandbox": true,
"session_id": "test-user",
"user_email": "",
"message_id": "sb_uuid",
"conversation_id": "sb_conv",
"response": {
"text": "[SANDBOX] Esta es una respuesta de prueba del Canal API.",
"quick_replies": ["Sí", "No"],
"voice_url": null
},
"timestamp": "2026-05-27T12:00:00Z"
}

voice_url: si el tenant tiene activadas las respuestas por voz (Ajustes del Bot), trae la URL de un audio MP3 con la respuesta hablada del agente. La URL es presignada y expira en ~1 hora — está pensada para reproducción inmediata, no para almacenarla. Es null cuando la voz está desactivada, el tenant no tiene saldo de audio, o la síntesis falló (la respuesta de texto llega igual). El mismo campo aparece en el evento done de POST /message/stream.

CódigoSignificadoCausa típica
400Bad RequestVersión no soportada, campo inválido, base64 malformado, audio que no se pudo transcribir o Idempotency-Key demasiado larga
401UnauthorizedAPI Key ausente, revocada o expirada
403ForbiddenCanal API no habilitado en el plan · tenant inactivo · token efímero en endpoint administrativo · token efímero scoped a otra sesión
404Not FoundLead o token efímero inexistente
409ConflictOtra solicitud con la misma Idempotency-Key sigue en proceso — reintenta en unos segundos
413Payload Too LargeCuerpo de la solicitud demasiado grande
422UnprocessableValidación del body fallida (email vacío, mensaje muy largo, tipo de archivo no permitido, archivo demasiado grande, etc.)
429Too Many RequestsRate limit excedido — espera 60 segundos y reintenta
503Service UnavailableSistema temporalmente no disponible — reintenta con backoff

Los errores HTTP (400, 401, 403, 404, 409, 429, 503) devuelven un cuerpo JSON con un detail de tipo string:

{ "detail": "Este canal no está habilitado en tu plan" }

Hay una excepción: una versión no soportada en X-Overtaker-Version devuelve 400 con detail como objeto: { "error": "Unsupported API version", "supported": ["1"] }.

Las fallas de validación (422) devuelven detail como una lista de errores por campo (formato estándar de FastAPI):

{
"detail": [
{
"loc": ["body", "message"],
"msg": "ensure this value has at most 5000 characters",
"type": "value_error.any_str.max_length"
}
]
}