Manejo de errores

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:

{
  "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

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:

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:

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:

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

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

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.

Plantilla de backoff para reintentos

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

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 para que los trabajos programados no reinicien a QPS completo inmediatamente después de un 429.

Notas específicas por framework

Páginas relacionadas

• Rate Limits
• Authentication
• API Overview
• MCP Tools