Referencia y límites

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 todos los contadores son por API Key.

Bucket	Límite	Endpoints
`write`	60 req/min	`POST /channel/message` — 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

Headers de rate limit

Cuando excedés un bucket recibís un 429 con estos headers de respuesta:

Header	Valor
`Retry-After`	`60` — segundos a esperar antes de reintentar
`X-RateLimit-Limit`	El máximo por minuto del bucket que excediste
`X-RateLimit-Remaining`	`0` (acabás de agotar el bucket)

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
Token efímero TTL	Default 30 min · máximo 4h
Rotación de webhook	Ventana dual: 72h
Timeout de webhook	10 segundos para responder HTTP 200
Reintentos de webhook	4 intentos: +10s, +30s, +2min, +10min
Versión soportada	`X-Overtaker-Version: 1`
API Keys activas	Máximo 3 por tenant

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/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"]
  },
  "timestamp": "2026-05-27T12:00:00Z"
}

Errores HTTP

Código	Significado	Causa típica
`400`	Bad Request	Versión no soportada, campo inválido o base64 malformado
`401`	Unauthorized	API Key ausente, revocada o expirada
`403`	Forbidden	Canal API no habilitado en el plan del tenant
`422`	Unprocessable	Validación del body fallida (email vacío, mensaje muy largo, etc.)
`429`	Too Many Requests	Rate limit excedido — reintentá respetando el header `Retry-After`
`503`	Service Unavailable	Sistema temporalmente no disponible — reintentá con backoff

Formato del cuerpo de error

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

{ "detail": "Canal API no habilitado para este tenant." }

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"
    }
  ]
}