Referencia y límites
Rate limits
Sección titulada «Rate limits»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.
| Bucket | Límite | Endpoints |
|---|---|---|
write | 60 req/min | POST /channel/message · POST /channel/message/stream · POST /channel/outbound — envío de mensajes reales |
read | 300 req/min | GET /ping · GET /conversations/.../messages · GET /leads/... |
sandbox | 600 req/min | POST /channel/message/sandbox — testing sin LLM |
Endpoints especiales:
| Endpoint | Límite |
|---|---|
POST /channel/webhook-secret/rotate | 5 req/min |
POST /channel/webhook-secret/confirm · /cancel | 10 req/min |
POST /channel/webhooks/test | 30 req/min |
POST · DELETE /channel/session-tokens | 60 req/min |
Qué recibes al exceder el límite
Sección titulada «Qué recibes al exceder el límite»Un 429 con este cuerpo:
{ "detail": "Too many requests. Please try again later." }Límites y restricciones
Sección titulada «Límites y restricciones»| Concepto | Valor |
|---|---|
| Tamaño de mensaje | Máximo 5.000 caracteres |
session_id | Máximo 200 caracteres |
contact_name | Máximo 120 caracteres (se recorta) |
Idempotency-Key | Máximo 200 caracteres · TTL 24h en /channel/message |
media_base64 | Unos 10 MB de archivo (14.000.000 de caracteres en base64); si se supera, 422 |
sample_payload de /webhooks/test | Máximo 8 KB |
| Token efímero TTL | Default 30 min · máximo 4h |
| Rotación de webhook | Ventana dual: 72h |
| Timeout de webhook | 10 segundos para responder con un código 2xx |
| Entrega de webhook | 4 intentos en total: el inicial y reintentos a los 10 s, 30 s y 2 min |
| Versión soportada | X-Overtaker-Version: 1 |
| API Keys activas | Máximo 3 de Canal API por tenant (las del conector MCP se cuentan aparte) |
Sandbox — probar sin gastar LLM
Sección titulada «Sandbox — probar sin gastar LLM»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/sandboxAuthorization: Bearer sk_live_YOUR_KEYContent-Type: application/jsonX-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. Esnullcuando 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 eventodonedePOST /message/stream.
Errores HTTP
Sección titulada «Errores HTTP»| Código | Significado | Causa típica |
|---|---|---|
400 | Bad Request | Versión no soportada, campo inválido, base64 malformado, audio que no se pudo transcribir o Idempotency-Key demasiado larga |
401 | Unauthorized | API Key ausente, revocada o expirada |
403 | Forbidden | Canal API no habilitado en el plan · tenant inactivo · token efímero en endpoint administrativo · token efímero scoped a otra sesión |
404 | Not Found | Lead o token efímero inexistente |
409 | Conflict | Otra solicitud con la misma Idempotency-Key sigue en proceso — reintenta en unos segundos |
413 | Payload Too Large | Cuerpo de la solicitud demasiado grande |
422 | Unprocessable | Validación del body fallida (email vacío, mensaje muy largo, tipo de archivo no permitido, archivo demasiado grande, etc.) |
429 | Too Many Requests | Rate limit excedido — espera 60 segundos y reintenta |
503 | Service Unavailable | Sistema temporalmente no disponible — reintenta con backoff |
Formato del cuerpo de error
Sección titulada «Formato del cuerpo de error»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" } ]}