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.

Reintenta publicaciones de forma segura con un Idempotency-Key

POST /twitter/tweets/create y POST /twitter/tweets/quote aceptan un header opcional Idempotency-Key. Usa un valor nuevo para cada publicación, como un UUID, y vuelve a enviar el mismo valor cuando reintentes esa publicación tras un timeout o un error de red:

curl https://api.twexapi.io/twitter/tweets/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a8d1-1f0b4c2a9e01" \
  -d '{"cookie": "auth_token=...; ct0=...", "tweet_content": "Hello from TwexAPI"}'

Las keys tienen de 1 a 255 caracteres ASCII visibles y son independientes por API key. Sin el header, cada solicitud publica. Las llamadas MCP a twexapi_write envían una key automáticamente: repetir exactamente la misma llamada en menos de 10 minutos devuelve el primer resultado.

Errores MCP

La autenticación falló antes de ejecutar la herramienta

Cuando falla la autenticación de MCP, no se ejecuta ninguna herramienta:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

Vuelve a iniciar sesión desde el cliente MCP, o corrige x-api-key o Authorization: Bearer, y repite la llamada. Consulta la referencia de herramientas MCP para ver todos los mensajes de autenticación.

Sin créditos

Cuando la cuenta se queda sin créditos, la conexión MCP sigue funcionando y explore es gratis, pero las demás llamadas devuelven un resultado de error sin llamar a la API:

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

Detén el trabajo y pide al usuario que recargue; reintentar no sirve.

Error de API devuelto por twexapi_request o twexapi_write

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

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}

Aplica la misma tabla de recuperación HTTP de arriba. No dejes que el modelo adivine una ruta nueva: vuelve a llamar a explore si la ruta pudo cambiar.

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

• Referencia de errores — mensajes por endpoint, códigos de X y criterios de reintento
• Rate Limits
• Authentication
• API Overview
• MCP Tools