---
title: "Manejo de errores"
description: "Recupera errores HTTP de TwexAPI, fallos de herramientas MCP, límites de créditos y reintentos de acciones de escritura."
---

TwexAPI devuelve errores en dos capas: **errores JSON-RPC de MCP** (autenticación antes de que se ejecute una herramienta) y **errores HTTP REST** (después de que la solicitud llegue a la API). Conserva los códigos de estado, los cuerpos de respuesta, los cursores y los ID para que los reintentos y la revisión humana sigan siendo seguros.

## Envelope de respuesta REST

Las llamadas exitosas devuelven:

```json
{
  "code": 200,
  "msg": "success",
  "data": {}
}
```

Cuando el estado HTTP no es `2xx`, trata la respuesta como un fallo aunque el cuerpo incluya un campo `code`. Registra el cuerpo completo, la ruta de la solicitud y cualquier cursor que ya hayas consumido.

## Recuperación por estado HTTP

| Estado | Significado | Acción |
| --- | --- | --- |
| `400` | Consulta inválida, campo faltante o cuerpo mal formado | Corrige la entrada. **No** reintentes sin cambios. |
| `401` | API key faltante o inválida | Reemplaza la credencial desde el [dashboard](https://twexapi.io/dashboard). Verifica el formato de `Authorization: Bearer`. |
| `403` | Créditos agotados, cuenta restringida o acción no permitida | Consulta [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get). Recarga o elimina pasos de escritura hasta que se restaure el acceso. |
| `404` | Tweet, usuario, lista o recurso no encontrado | Verifica ID, nombres de usuario y vigencia del cursor. |
| `422` | Validación fallida en entrada estructurada | Corrige los campos del schema documentados en la página del endpoint. No reintentes sin cambios. |
| `429` | Límite de tasa excedido | Haz backoff siguiendo [Rate Limits](/guides/rate-limits). Conserva `next_cursor` y las filas completadas. |
| `5xx` | Fallo transitorio del servicio o de la obtención upstream | Reintenta con backoff exponencial y un límite máximo. |

## Créditos y balance

Las lecturas y escrituras medidas consumen créditos de la cuenta. Cuando un trabajo procesa muchas páginas, verifica el balance antes y después de ejecuciones largas:

```bash
curl --request GET \
  --url 'https://api.twexapi.io/balance' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Si las respuestas `403` mencionan créditos o acceso:

1. Detén los trabajos programados que sigan golpeando la API.
2. Confirma el balance en el dashboard.
3. Reanuda desde el último cursor guardado después de restaurar los créditos.

## Reintentos seguros con paginación

Para búsqueda, seguidores, timelines e historial de DM:

- Almacena `next_cursor`, `has_next_page` y cualquier `task_id` fuera de la conversación del agente.
- Después de `429` o `5xx`, reintenta el **mismo cursor**, no la página siguiente.
- Después de `400`, `404` o `422`, inspecciona ID y parámetros de consulta antes de reintentar.

## Acciones de escritura

Los endpoints de escritura (tweet, respuesta, like, follow, envío de DM) requieren:

- Una API key de TwexAPI válida
- Una cookie de Twitter o `auth_token` guardada en la solicitud

Reglas de recuperación:

| Situación | Acción |
| --- | --- |
| `401` en escritura | Corrige la API key y las credenciales de cookie antes de reintentar. |
| `403` en escritura | Confirma créditos y que la cuenta conectada aún tenga permiso. |
| Éxito ambiguo | Busca el tweet, DM o estado de engagement con un endpoint de lectura antes de duplicar la acción. |
| Flujos de agentes | Requiere aprobación humana antes de cualquier llamada MCP con `read_only: false`. |

Public docs focus on API-key reads.

## Errores MCP

### Autenticación fallida antes de ejecutar la herramienta

Cuando falla la autenticación MCP, `explore` y `twexapi_request` no se ejecutan:

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}
```

Corrige `x-api-key` o `Authorization: Bearer` en el cliente MCP, luego vuelve a ejecutar la llamada a la herramienta.

### Error de API devuelto a través de `twexapi_request`

Cuando falla la llamada REST subyacente, conserva el resultado de la herramienta:

```json
{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}
```

Aplica la misma tabla de recuperación HTTP de arriba. No pidas al modelo que adivine una ruta nueva—llama a `explore` de nuevo si la ruta pudo haber cambiado.

## Errores de SDK y CLI

Los SDK generados mapean fallos HTTP a excepciones nativas del lenguaje. Captura errores en el límite del trabajo, registra el código de estado y el cuerpo de respuesta, y enruta `429`/`5xx` a políticas de reintento.

Ejemplo en Python:

```python
import requests

try:
    response = requests.get(
        "https://api.twexapi.io/balance",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        timeout=30,
    )
    response.raise_for_status()
except requests.HTTPError as exc:
    status = exc.response.status_code
    body = exc.response.text
    if status == 429:
        # Back off, preserve cursor, retry later
        ...
    elif status in (400, 404, 422):
        # Fix input; do not retry unchanged
        ...
    raise
```

Consulta patrones específicos por lenguaje en cada [página de SDK](/sdks).

## Plantilla de backoff para reintentos

Usa backoff exponencial con límite para `429` y `5xx`:

```python
retry_delays_seconds = [5, 15, 45, 120]

for delay in retry_delays_seconds:
    response = call_twexapi()
    if response.ok:
        break
    if response.status_code in (429, 500, 502, 503, 504):
        time.sleep(delay)
        continue
    break  # 4xx other than 429: stop and fix input
```

Combina el backoff con [Rate Limits](/guides/rate-limits) para que los trabajos programados no reinicien a QPS completo inmediatamente después de un `429`.

## Notas específicas por framework

| Runtime | Orientación |
| --- | --- |
| [LangChain](/guides/langchain) | Valida modelos de handoff; detén el grafo en `401`. |
| [Prefect](/guides/prefect) | Usa reintentos de tareas con jitter; almacena cursores en el estado de la tarea. |
| [n8n / Zapier / Make](/guides/no-code-workflow-handoff) | Enruta `401`/`403` a alertas de ops; retrasa replays de `429`. |
| [Agentes MCP](/mcp/agent-handoff) | Nunca descartes `next_cursor` después de un éxito parcial. |

## Páginas relacionadas

- [Rate Limits](/guides/rate-limits)
- [Authentication](/authentication)
- [API Overview](/api-reference/overview)
- [MCP Tools](/mcp/tools)