Códigos de error de la API de Twitter y referencia de estados HTTP

Resuelve errores de la API de Twitter/X en TwexAPI: HTTP 401, 403, 429 y 5xx, invalid auth_token, tweets duplicados, límites de mensajes directos y reintentos seguros.

TwexAPI informa los fallos de la API de Twitter/X mediante estados HTTP y, cuando están disponibles, códigos de error de X. Un 401 requiere corregir las credenciales; un 403, resolver un problema de acceso o de la cuenta; y un 429, esperar a que se restablezca el límite de solicitudes. Revisa el cuerpo de la respuesta antes de reintentar.

Usa esta referencia para resolver códigos de error de la API de Twitter, invalid auth_token, tweets duplicados y límites de mensajes directos. Las rutas de los endpoints siguen la referencia de la API actual. Para errores de MCP, recuperación de la paginación y ejemplos de SDK, consulta Manejo de errores.

Los mensajes y códigos de X que aparecen a continuación son ejemplos para diagnosticar problemas; la estructura de las respuestas y su correspondencia con los estados HTTP pueden variar según el endpoint. Consulta tanto el esquema del endpoint como la respuesta real.

Encuentra la solución al error de la API de Twitter

• HTTP 401 / Invalid auth_token: revisa tanto tu clave de API de TwexAPI como las credenciales de sesión de X que usan los endpoints de escritura. Consulta Autenticación.
• HTTP 403: revisa si el mensaje indica créditos insuficientes, publicaciones protegidas, restricciones de la cuenta o requisitos de Premium. Repetir una solicitud sin cambios no restablece el acceso.
• HTTP 429 / Too Many Requests: respeta Retry-After o retry_after y distingue entre la limitación de solicitudes y el límite diario de una cuenta de X. Consulta Límites de solicitudes.
• HTTP 500 / 502 / 503: reintenta los fallos transitorios de lectura con esperas progresivas que tengan un máximo. Comprueba si una escritura ya se completó antes de repetirla.
• Códigos de X 187, 344 o 502: son códigos de X, distintos de los estados HTTP. Consulta la tabla de códigos de Twitter/X y las preguntas sobre reintentos.

Formato de las respuestas de error

Conserva el estado HTTP y el cuerpo JSON completo. Las respuestas de TwexAPI pueden incluir code y msg; los errores de validación de solicitudes usan detail:

{
  "code": 500,
  "msg": "Internal server error"
}

{
  "detail": [
    {
      "loc": ["body", "cookie"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Si la respuesta incluye metadatos adicionales de X, consérvalos:

• error: un mensaje de error, cuando se proporciona. No supongas que todos los endpoints usan este campo.
• twitter_error_code: un código de error de X, cuando se proporciona. Es independiente del estado HTTP; por ejemplo, el código de X 502 se refiere a un límite de mensajes directos.
• retry_after: los segundos que debes esperar, cuando se proporciona. Respeta también el encabezado HTTP Retry-After.

No exijas que existan campos opcionales ni decidas qué hacer basándote solo en el texto exacto del mensaje. Un estado HTTP distinto de 2xx indica un fallo, aunque el cuerpo contenga un code diferente.

Errores comunes en todos los endpoints

Revisa estas condiciones en cualquier solicitud. Los mensajes exactos pueden variar.

Estados HTTP de la API de Twitter

Códigos de error de la API de Twitter/X

Cuando la respuesta incluya un código de X, usa los siguientes significados. Son códigos de X, no estados HTTP, y no todos los endpoints exponen twitter_error_code.

Lectura de tweets y búsqueda

Se aplica a POST /twitter/{screen_name}/timeline/page, /twitter/tweets-replies/page y /twitter/advanced_search/page.

Publicaciones e interacciones

Crear un tweet

POST /twitter/tweets/create

Usa tweet_content, el campo opcional reply_tweet_id y tus credenciales de X en cookie. Consulta Crear un tweet o una respuesta.

Me gusta / Retuitear / Guardar en marcadores

POST /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

DELETE /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

Eliminar un tweet

POST /twitter/tweets/delete-batch

Proporciona target_id para eliminar un solo tweet. Si lo omites, seleccionas la eliminación masiva; conserva los campos de la solicitud original al recuperarte de errores.

Seguir / Dejar de seguir

POST /twitter/user/follow · DELETE /twitter/user/follow

Actualizar el perfil / Avatar / Imagen de encabezado

POST /twitter/profile

Usa profile_image y profile_banner para las URL de las imágenes, y cookie para las credenciales de X.

Archivos multimedia adjuntos

Adjunta archivos multimedia al crear tweets o enviar mensajes directos; la referencia actual no incluye una ruta independiente para cargar archivos multimedia. Al crear un tweet, media_urls admite hasta cuatro imágenes, un GIF o un video. No combines un GIF o video con otros archivos multimedia. Corrige las URL inaccesibles, los formatos no compatibles o los tamaños de archivo rechazados antes de reintentar. Sigue el esquema del endpoint para los nombres de los campos y sus restricciones.

Mensajes directos

POST /v3/twitter/send-dm · /v3/twitter/dm-history · /v3/twitter/conversations

Para comprobar los permisos, usa POST /v2/dm/status. Consulta Enviar un mensaje directo.

Lectura de datos

POST /v2/tweet/detail · /twitter/tweets/lookup · /twitter/users/by_ids · /v3/twitter/users/followers · /v3/twitter/users/following · /twitter/tweets/thread_by_id · /twitter/tweets/{tweet_id}/replies/page

GET /twitter/{screen_name}/about · /twitter/search-user/{keyword}/{target_count}

Artículos

POST /x/article · GET /x/article/{tweet_id}/markdown

Para escrituras: POST /x/articles/draft · PUT /x/articles/{article_id}/cover · /x/articles/{article_id}/title · /x/articles/{article_id}/content · POST /x/articles/{article_id}/publish o /x/articles/publish.

El requisito de Premium indicado a continuación se aplica a la publicación de artículos. Usa preferentemente el flujo de artículos paso a paso para conservar article_id y reintentar solo el paso que falló.

Guía de reintentos

Consejo: Usa esperas progresivas con un máximo y variación aleatoria para 429 y errores 5xx transitorios. Para 400/401/403/404/409/422, corrige primero los datos de entrada, las credenciales o el acceso de la cuenta.

Preguntas sobre errores y reintentos de la API de Twitter

¿Por qué la API de Twitter devuelve 401 o invalid auth_token?

HTTP 401 puede indicar que falta tu clave de API de TwexAPI o que no es válida. En los endpoints de escritura, Invalid auth_token o el código de X 32 también pueden indicar que la sesión de X venció. Corrige el encabezado Bearer o renueva las credenciales de X proporcionadas en cookie antes de reintentar.

¿Cuál es la diferencia entre los errores 403 y 429 de la API de Twitter?

HTTP 403 indica un problema de acceso, como créditos insuficientes, contenido privado, una cuenta restringida o una acción exclusiva de Premium. HTTP 429 indica un límite de solicitudes o de la cuenta. Corrige la causa de un 403; después de un 429, espera a que se restablezca el límite indicado.

¿Cómo resuelvo el error 429 Too Many Requests de la API de Twitter?

Respeta la espera de Retry-After o retry_after cuando se proporcionen y luego continúa con menos solicitudes simultáneas y esperas progresivas que tengan un máximo. Un límite diario de tweets o mensajes directos requiere esperar su período de restablecimiento, no solo una pausa breve. Conserva el cursor de la página que falló al reintentar una lectura.

¿Qué significa el código de error 187 de Twitter?

El código de error de X 187 significa que el contenido del tweet está duplicado. Comprueba si la escritura anterior ya creó la publicación. Si quieres publicar algo diferente, cambia tweet_content en vez de repetir la misma solicitud.

¿Qué significa el código de error 344 de Twitter?

El código de error de X 344 indica una restricción temporal de publicación asociada a la red o a la IP. Aumenta la espera, revisa cualquier proxy que hayas proporcionado y consulta la cronología de la cuenta antes de reintentar la escritura. Es un código de error de X, no un estado HTTP.

¿Debo reintentar los errores 500, 502 o 503 de la API de Twitter?

Reintenta los fallos transitorios de lectura con esperas progresivas que tengan un máximo y variación aleatoria. Si una escritura agota el tiempo de espera o devuelve 5xx, revisa primero la cronología, el historial de mensajes directos o el estado de la interacción. Una respuesta fallida no demuestra que la escritura no se haya aplicado.

¿Debo reintentar un error de validación 422 de TwexAPI?

No reintentes con los mismos datos de entrada. TwexAPI usa HTTP 422 para los errores de validación de solicitudes. Revisa detail para identificar el campo que falló, su ubicación y el tipo de error; luego corrige la solicitud según el esquema del endpoint.

¿El código de error 502 de Twitter es lo mismo que HTTP 502?

No. El código de error de X 502 se refiere a un límite diario de solicitudes de mensajes directos y puede aparecer junto con HTTP 429. HTTP 502 indica un fallo en la respuesta del servicio de origen. Lee tanto el estado HTTP como twitter_error_code, cuando se proporcione, antes de elegir una política de reintentos.

Páginas relacionadas

• Manejo de errores — MCP, SDK y recuperación de la paginación
• Autenticación — claves de API y credenciales de sesión de X
• Límites de solicitudes — esperas progresivas y capacidad de procesamiento
• Descripción general de la API — referencia actual de endpoints