Errores y límites

La forma de un error

Todos los errores de la API salen con el mismo cuerpo, sin importar la operación ni el código:

{
  "error": {
    "code": "outside_messaging_window",
    "message": "La ventana de 24 horas está cerrada. Envía una plantilla aprobada.",
    "detail": { "last_inbound_at": "2026-09-03T14:22:00Z" },
    "request_id": "req_794929f67ff26af6"
  }
}

Ramifica en code, nunca en message ni solo en el estado HTTP. Varios códigos comparten estado (422 cubre desde un campo faltante hasta una plantilla pausada) y cada uno pide una acción distinta.

Tabla completa de códigos

400 La petición está mal formada

401 No sabemos quién eres

402 Falta cupo

403 Sabemos quién eres, pero no puedes

404 No existe

405 Método equivocado

409 Conflicto con algo en curso

422 La petición se entiende, pero no puede ejecutarse

429 Vas demasiado rápido

En los tres, si era un envío, reintenta con la misma Idempotency-Key: un 429 libera la clave, así que el reintento se ejecuta de verdad.

Los dos primeros son límites nuestros y traen Retry-After en segundos. El tercero viene de WhatsApp y no lo trae: ahí aplica tu propia espera creciente.

500 y 502 El problema es nuestro o del proveedor

Límites de uso

Por cuenta y por minuto:

El límite es por cuenta, no por clave: varias claves comparten la misma cuota, a propósito, para que crear una clave nueva no sea una forma de esquivarlo.

Además hay un tope de 60 envíos por minuto y por canal de WhatsApp, independiente de tu cuota. Existe para que varias claves de la misma cuenta no se sumen sobre un mismo número, y para que un bucle con reintentos no lo sature. Cuando muerde, la respuesta es 429 channel_throttled aunque te sobre cuota de cuenta.

Los headers de cuota

Las respuestas correctas traen:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1788564060

X-RateLimit-Reset es el momento en que el contador vuelve a cero, en segundos desde la época Unix. Al superar cualquiera de los dos límites de arriba, la respuesta es 429 (rate_limited o channel_throttled), repite esos headers y agrega Retry-After con los segundos que faltan.

No todas las respuestas de error incluyen los headers de cuota (una petición rechazada antes de contarse no consume nada), así que no dependas de su presencia para decidir.

Topes de los campos

Todo lo que mandas tiene un largo máximo. Pasarse responde 422 validation_error con el campo señalado en detail, antes de tocar WhatsApp: no gasta cupo ni consume el tope de envíos de tu canal.

Los valores de content.variables son siempre texto. Un número o un booleano sin comillas ({"1": 1500}) se rechaza con validation_error: conviértelo tú, para que el formato que ve tu cliente final sea el que tú elegiste y no el que elija un serializador.

Paginación

Los listados (GET /v1/contacts, GET /v1/channels, GET /v1/groups y sus integrantes) paginan por cursor, nunca por número de página. Un cursor es un texto opaco: no lo interpretes ni lo construyas, solo devuélvelo tal cual.

curl "https://api.alttos.ai/api/public/v1/contacts?limit=2" \
  -H "Authorization: Bearer $ALTTOS_API_KEY"

{
  "data": [
    {
      "id": "c16c6b03-3990-4097-9819-5f80ca66fefb",
      "name": "Contacto 1",
      "phone": "573000000001",
      "email": "c1@ejemplo.com",
      "tags": ["api"],
      "created_at": "2026-09-04T23:20:30.196822Z",
      "last_activity_at": "2026-09-04T23:20:30.196822Z"
    },
    {
      "id": "6b376bb0-21b8-4ad2-81f3-86e25ad0670e",
      "name": "Contacto 2",
      "phone": "573000000002",
      "email": "c2@ejemplo.com",
      "tags": ["api"],
      "created_at": "2026-09-04T23:20:30.196822Z",
      "last_activity_at": "2026-09-04T23:20:30.196822Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzb3J0IjoiY3JlYXRlZF9hdCIsImsiOlsiMjAyNi0wOS0wNFQyMzoyMDozMC4xOTY4MjIrMDA6MDAiLCI2YjM3NmJiMC0yMWI4LTRhZDItODFmMy04NmUyNWFkMDY3MGUiXX0"
}

Para la página siguiente, pasa ese valor en cursor:

curl "https://api.alttos.ai/api/public/v1/contacts?limit=2&cursor=eyJ2IjoxLCJzb3J0Ijoi..." \
  -H "Authorization: Bearer $ALTTOS_API_KEY"

Cuando next_cursor es null, llegaste al final. limit acepta entre 1 y 100 (por defecto 50); fuera de ese rango la respuesta es 422 validation_error.

Los contactos vienen del más reciente al más antiguo. El cursor apunta a una posición concreta del listado, no a un número de página, así que recorrer todas las páginas no salta ni repite elementos aunque se creen contactos mientras recorres.

GET /v1/channels pagina igual, con los mismos limit y cursor, pero del más antiguo al más reciente. Un cursor pertenece a la lista que lo emitió: pasarle a /v1/channels uno de /v1/contacts responde 400 invalid_cursor en vez de servir una página incoherente.

Buscar en vez de recorrer

Si lo que quieres es un contacto puntual, no recorras el listado: busca por coincidencia exacta.

# Por teléfono (acepta espacios, paréntesis y el prefijo +; comparamos por dígitos)
curl "https://api.alttos.ai/api/public/v1/contacts?phone=%2B573000000000" \
  -H "Authorization: Bearer $ALTTOS_API_KEY"
 
# Por email (no distingue mayúsculas)
curl "https://api.alttos.ai/api/public/v1/contacts?email=ana%40ejemplo.com" \
  -H "Authorization: Bearer $ALTTOS_API_KEY"

La respuesta tiene la misma forma que el listado: data con lo que coincida (vacío si nada coincide) y next_cursor.

Compatibilidad

Dentro de /v1 solo hacemos cambios aditivos: campos nuevos en una respuesta, parámetros opcionales nuevos, códigos de error nuevos para casos que antes salían más genéricos. Nunca quitamos un campo ni le cambiamos el significado.

Para que eso sea seguro para ti, tu integración tiene que cumplir cuatro reglas:

1. Ignora los campos que no conozcas. Un parser que falla ante una clave nueva convierte un cambio compatible en una caída. Lo mismo con los valores: kind, status y capabilities.send pueden crecer; trata como no soportado el que no reconozcas.
2. Ramifica en code, no en message. El texto cambia; el código no.
3. Trata un code desconocido por su estado HTTP. 4xx es “corrige”; 5xx es “reintenta”.
4. Manda exactamente lo que el contrato declara. Al revés que al leer, al escribir no somos tolerantes: un campo de más o un parámetro de query inventado salen como 422 validation_error. Es a propósito — un campo ignorado en silencio envía el mensaje sin el dato que creías estar mandando.

Un cambio que sí rompa el contrato saldría bajo un prefijo nuevo (/v2), con aviso previo. /v1 no se rompe.