# Solución de problemas de la API: errores comunes

_API · 4 min de lectura · Actualizado 2026-10-23 · https://lanachat.ai/guides/es/api-troubleshooting/_

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:

```json
{ "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:

1. El encabezado es exactamente `Authorization: Bearer <token>`, con la palabra `Bearer` y un espacio.
2. El token fue copiado completo. Se muestra solo una vez, cuando lo creas.
3. 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.
4. 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`.

1. Encuentra el permiso en la columna **Permission** del endpoint.
2. En **Users › API & MCP**, presiona **Edit** en el token y márcalo.
3. 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=100` en 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](https://lanachat.ai/guides/es/api-telegram-accounts/).

## 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](https://lanachat.ai/guides/es/api-overview/) 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.

1. **Responde rápido.** Devuelve `2xx` de inmediato, luego haz el trabajo lento en segundo plano.
2. **Verifica la firma en el cuerpo crudo**, antes de cualquier análisis JSON. Un cuerpo analizado y re-serializado nunca coincide.
3. **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.
4. **Acepta ambos valores `v1`** durante una rotación de secreto.
5. **Prueba** con `POST /webhooks/{id}/test` (Planned), que envía un `ping`, 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](https://lanachat.ai/guides/es/api-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](https://lanachat.ai/guides/es/get-help/).

## Artículos relacionados

- [API de LanaChat: inicio rápido, autenticación y errores](https://lanachat.ai/guides/es/api-overview/)
- [API: webhooks, eventos y firmas](https://lanachat.ai/guides/es/api-webhooks/)
- [API: miembros del equipo, roles y tokens de acceso](https://lanachat.ai/guides/es/api-team/)
- [Recetas rápidas de API: copiar, pegar, ejecutar](https://lanachat.ai/guides/es/api-recipes/)