Solución de problemas de la API: errores comunes
Cada endpoint en la referencia está marcado como Planned hoy: es el contrato publicado y aún no responde. Esta página lista los errores que la API devolverá, para que tu código pueda manejarlos desde el primer día.
Lee el error primero #
Cada error responde con un estado 4xx o 5xx con el mismo cuerpo:
{ "error": { "code": "forbidden", "message": "…" } }message es una frase en inglés simple que indica qué salió mal. Regístralo, pero ramifica tu código según code, nunca según message.
401 unauthorized #
La API no aceptó tu token. Verifica, en este orden:
- El encabezado es exactamente
Authorization: Bearer <token>, con la palabraBearery un espacio. - El token fue copiado completo. Se muestra solo una vez, cuando lo creas.
- El token sigue activo. En Users › API & MCP, la tabla Access tokens muestra la expiración y estado de cada token, y Show revoked tokens lista los antiguos.
- Si expiró o fue revocado, crea uno nuevo (o Rotate el token) y actualiza tu variable de entorno.
403 forbidden #
El token es válido pero carece del permiso que el endpoint requiere. Cada endpoint en la referencia lista su permiso, como can_fan_read o can_sales_read.
- Encuentra el permiso en la columna Permission del endpoint.
- En Users › API & MCP, presiona Edit en el token y márcalo.
- Llama a
GET /v1/workspace: la respuesta lista lo que el token puede hacer.
Un 403 también ocurre cuando un token que no es de propietario envía el encabezado LanaChat-Workspace. Elimínalo.
429 rate_limited #
Cada token puede enviar 600 solicitudes por minuto. Cada respuesta incluye RateLimit-Remaining y RateLimit-Reset.
- Espera el número de segundos en
Retry-After, luego intenta de nuevo. - Navega listas con
limit=100en lugar de una llamada por ítem. - Enviar mensajes a fans también está limitado por los propios límites de Telegram: consulta Telegram accounts and pools.
Los otros códigos #
| Status | code | Qué hacer |
|---|---|---|
| 400 | invalid_request | Falta un campo o tiene formato incorrecto: message indica cuál |
| 402 | insufficient_balance | Recarga antes de comprar |
| 404 | not_found | El id no existe en este workspace: verifica que usas el token correcto |
| 409 | conflict | El cambio viola una regla, o se reutilizó un Idempotency-Key con un cuerpo distinto |
| 500 | server_error | Reintenta más tarde con el mismo Idempotency-Key |
Envía un Idempotency-Key en cada POST: un reintento nunca hace el trabajo dos veces. El asistente en the quick start reintenta 429 y 5xx por ti.
Webhooks que fallan #
Una entrega se considera fallida cuando tu servidor no responde con un 2xx en 10 segundos.
- Responde rápido. Devuelve
2xxde inmediato, luego haz el trabajo lento en segundo plano. - Verifica la firma en el cuerpo crudo, antes de cualquier análisis JSON. Un cuerpo analizado y re-serializado nunca coincide.
- Revisa el reloj de tu servidor. Un timestamp con más de 5 minutos de antigüedad es rechazado por el código de ejemplo, así que un reloj desfasado rechaza todas las entregas.
- Acepta ambos valores
v1durante una rotación de secreto. - Prueba con
POST /webhooks/{id}/test(Planned), que envía unping, y reenvía una entrega con/deliveries/{delivery_id}/retry(Planned) una vez que arreglaste tu lado.
Las entregas fallidas se reintentan 8 veces durante unas 24 horas. Tras 3 días de fallos, el endpoint se pausa; reanúdalo con PATCH /webhooks/{id} (Planned). El mismo evento puede llegar dos veces: ignora duplicados por id. Consulta Webhooks.
¿Sigues atascado? #
Abre el globo de ayuda en la esquina inferior derecha de la Console y escribe al equipo con el endpoint, el estado, el code y la hora de la llamada. Nunca pegues el token. Consulta Get help.