---
title: "Códigos de error de la API de Twitter y referencia de estados HTTP"
description: "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."
lastModified: "2026-10-08"
sidebar:
  label: "Referencia de errores"
seo:
  title: "Códigos de error de la API de Twitter: 401, 403, 429 y reintentos"
search:
  tags: ["códigos de error de la API de Twitter", "errores de la API de X", "invalid auth_token", "429 Too Many Requests", "twitter_error_code"]
---

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](/es/api-reference/overview) actual. Para errores de MCP, recuperación de la paginación y ejemplos de SDK, consulta [Manejo de errores](/es/guides/error-handling).

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](/es/authentication#operaciones-de-escritura-y-byoc-tráiger-tus-propias-cookies).
- **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](/es/guides/rate-limits).
- **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](#códigos-de-error-de-la-api-de-twitterx) y las [preguntas sobre reintentos](#preguntas-sobre-errores-y-reintentos-de-la-api-de-twitter).

## 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`:

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

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

| Estado | Mensaje | Qué significa | Qué hacer |
| --- | --- | --- | --- |
| **401** | `Invalid or missing API key` | Falta tu clave de API o es incorrecta | Revisa el encabezado `Authorization: Bearer <key>` |
| **400** | `Missing required … param: <x>` | Falta un campo o parámetro obligatorio, o no es válido | Corrige la solicitud |
| **429** | `Please try again shortly.` (nuestra capacidad) · `Rate limit exceeded…` · o un mensaje de límite de X | Demasiadas solicitudes, capacidad de nuestro servicio o un **límite de la cuenta de X** (p. ej., límite diario de mensajes directos o tweets; puede incluir `twitter_error_code`) | Respeta `retry_after` / `Retry-After`; los límites diarios de la cuenta requieren una espera más larga |
| **403** | Créditos agotados o acceso denegado | Créditos insuficientes o falta de permisos de la cuenta | Revisa el saldo y el acceso de la cuenta |
| **422** | Error de validación (`detail`) | Los campos de la solicitud no pasaron la validación del esquema | Corrige los campos indicados en `detail`; no reintentes sin cambios |
| **500** | `Internal server error` | Ocurrió un error temporal | Reintenta en breve |

:::warning
**Dos tipos de 401.** Un `401` en el nivel de la API significa que tu **clave de API** es incorrecta. En los endpoints de escritura (publicar, dar Me gusta, actualizar el perfil), un `401` también puede indicar que las **credenciales de sesión de X que proporcionaste en `cookie`** no son válidas o vencieron; el mensaje puede decir `Invalid auth_token` o `Could not authenticate you`. En ese caso, renueva las credenciales de sesión de X. Consulta [Autenticación](/es/authentication#operaciones-de-escritura-y-byoc-tráiger-tus-propias-cookies).
:::

## Estados HTTP de la API de Twitter

| Estado | Significado |
| --- | --- |
| **200** | Éxito |
| **202** | Aceptado; si un endpoint devuelve este estado, la acción está pendiente |
| **400** | Solicitud incorrecta, parámetros faltantes o no válidos, URL de proxy no válida o archivo multimedia demasiado grande |
| **401** | No autorizado, clave de API incorrecta o `auth_token` no válido o vencido |
| **403** | Prohibido: créditos insuficientes, una **cuenta de destino protegida/privada o suspendida** (no se pueden leer sus publicaciones), una cuenta suspendida o bloqueada que estás usando, una restricción de permisos o una acción exclusiva de Premium |
| **404** | No encontrado; el usuario, tweet o recurso no existe |
| **409** | Conflicto, tweet duplicado |
| **410** | Recurso no disponible; revisa el cuerpo para conocer los detalles de la suspensión de la cuenta |
| **422** | Falló la validación de la solicitud; revisa `detail` y corrige los datos de entrada |
| **423** | Si X lo devuelve: la cuenta está bloqueada o requiere verificación |
| **429** | Demasiadas solicitudes; se alcanzó un límite de solicitudes |
| **500 / 502 / 503** | Error temporal del servidor o del servicio de origen; reintenta |

## 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`.

| Código | Significado | Qué hacer |
| --- | --- | --- |
| **32** | No se pudo autenticar tu cuenta | Renueva las credenciales de sesión de X proporcionadas en `cookie` |
| **63** | La cuenta de destino está suspendida | Usa una cuenta accesible o espera a que se restablezca el acceso |
| **64** | Tu cuenta está suspendida | Usa otra cuenta |
| **131** | Error interno temporal de X | Reintenta |
| **139** | Ya diste Me gusta | Confirma el estado actual; no repitas la acción |
| **144** | No se encontró ningún tweet con ese ID | Se eliminó el tweet o el ID es incorrecto |
| **187** | Tweet duplicado | Confirma la publicación anterior y cambia el texto si quieres crear una nueva |
| **226** | La solicitud pareció automatizada | Reintenta |
| **326** | Cuenta bloqueada temporalmente | Desbloquéala en `x.com/account/access` y luego reintenta |
| **327** | Ya retuiteaste | Confirma el estado actual; no repitas la acción |
| **344** | Publicación limitada temporalmente (limitación de red/IP, no de la cuenta) | Aumenta la espera y revisa el proxy si proporcionaste uno; confirma el resultado de la escritura antes de reintentar |
| **349** | No puedes enviar mensajes a este usuario | El destinatario no acepta tus mensajes directos |
| **399** | Falló el inicio de sesión en X | Revisa las credenciales de sesión de X |
| **433** | Respuestas restringidas / se requiere Premium | El tweet restringe quién puede responder o la acción requiere X Premium |
| **465** | No se puede retuitear un tweet antiguo | El tweet es demasiado antiguo para retuitearlo |
| **476** | No se permite enviar solicitudes de mensajes | La cuenta no puede enviar solicitudes de mensajes directos |
| **502** | Se alcanzó el límite diario de mensajes directos (solicitudes de mensajes) | Espera 24 horas o usa una cuenta de X Premium para obtener límites más altos |

## Lectura de tweets y búsqueda

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

| Estado | Mensaje | Qué hacer |
| --- | --- | --- |
| **403** | `This account's posts are not available. The account is protected (private), suspended, or no longer active.` | **No reintentes sin cambios**: el acceso debe cambiar para que la solicitud pueda completarse. Solo los seguidores aprobados pueden leer las publicaciones de la cuenta de destino. Dirige la solicitud a una cuenta pública. |
| **403** | `This account is suspended, so its posts are not available.` | La cuenta de destino está suspendida. Usa una cuenta accesible o espera a que se restablezca el acceso. |
| **502** | `Upstream returned an unexpected response — please retry.` | Fallo del servicio de origen. **Reintenta con esperas progresivas que tengan un máximo**; conserva el mismo cursor. |

:::info
Un `403` causado por una **cuenta de destino protegida o suspendida** requiere un cambio de acceso o de cuenta. Un `502` puede ser transitorio. Revisa el estado y el cuerpo antes de elegir una política de reintentos.
:::

## 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](/es/api-reference/tweet-actions-endpoints/create-tweet-twitter-tweets-create-post).

| Estado | Código | Mensaje | Qué hacer |
| --- | --- | --- | --- |
| **409** | 187 | `Status is a duplicate.` | Comprueba si la publicación ya existe; cambia el texto para crear una nueva |
| **403** | 433 | `The original Tweet author restricted who can reply…` | El tweet no permite tu respuesta |
| **403** | 433 | El texto extenso o video largo requiere Premium | Usa una cuenta Premium o acorta el contenido |
| **403** | n/a | No eres miembro de la comunidad | Únete primero a la comunidad |
| **429** | 344 | Publicación limitada temporalmente (limitación de red/IP) | Aumenta la espera; revisa el proxy proporcionado y confirma si se creó la publicación |
| **502** | n/a | `X returned an empty result` (resultado sin confirmar) | Lee la cronología de la cuenta antes de reintentar; el resultado de la escritura no está confirmado |
| **400** | n/a | `File size exceeds…` | Reduce el tamaño del archivo multimedia |
| **503** | 226 | `This request looks automated` | Aumenta la espera y comprueba el resultado de la escritura antes de reintentar |
| **502 / 503** | n/a | Error temporal de conexión | Reintenta (si proporcionaste un `proxy`, confirma que funciona) |

### 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`

| Estado | Código | Mensaje | Qué hacer |
| --- | --- | --- | --- |
| **403** | n/a | `User is suspended, deactivated or offboarded` | La cuenta no está disponible; usa otra cuenta |
| **401** | 32 | `Could not authenticate you` | Renueva las credenciales de sesión de X proporcionadas en `cookie` |
| **403** | 465 | `not permitted to retweet an outdated Tweet` | El tweet es demasiado antiguo para retuitearlo |
| Varía | 139 / 327 | Ya diste Me gusta / ya retuiteaste | Confirma el estado actual; no repitas la acción |
| **429** | n/a | Límite de solicitudes | Reduce la frecuencia y luego reintenta |
| **502 / 503** | n/a | Error temporal de conexión | Reintenta |

### 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.

| Estado | Mensaje | Qué hacer |
| --- | --- | --- |
| **404** | `No status found with that ID` | Ya se eliminó o el ID es incorrecto |
| **403** | No eres el autor | Solo puedes eliminar tus propios tweets |
| **401** | `auth_token` no válido | Renueva las credenciales de sesión de X |

### Seguir / Dejar de seguir

**POST** `/twitter/user/follow` · **DELETE** `/twitter/user/follow`

| Estado | Mensaje | Qué hacer |
| --- | --- | --- |
| **404** | `User not found` | Revisa el nombre de usuario o ID |
| **403** | Restringido | Tu cuenta o la cuenta de destino no lo permite |
| **401** | `auth_token` no válido | Renueva las credenciales de sesión de X |
| **429** | Límite para seguir cuentas | Espera y luego reintenta |

### 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.

| Estado | Mensaje | Qué hacer |
| --- | --- | --- |
| **401** | `Invalid auth_token - could not fetch credentials` | Renueva las credenciales de sesión de X |
| **400** | Imagen demasiado grande / formato incorrecto | Corrige la imagen |

## 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](/es/api-reference/dm-endpoints/send-dm-api-v3-v3-twitter-send-dm-post).

| Estado | Código | Mensaje | Qué hacer |
| --- | --- | --- | --- |
| **429** | 502 | `You've hit your daily message request limit. Subscribe to Premium for higher limits.` | Espera 24 h o usa una cuenta Premium |
| **403** | 476 | `Sender is not verified to send message requests` | La cuenta no puede enviar solicitudes de mensajes directos |
| **403** | 349 | `Cannot send messages to this user` | El destinatario no acepta tus mensajes directos |
| **401** | 32 | `Could not authenticate you` | Renueva las credenciales de sesión de X |
| **404** | n/a | Conversación / usuario no encontrado | Revisa el destinatario |

## 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}`

| Estado | Mensaje | Qué hacer |
| --- | --- | --- |
| **404** | `Tweet not found: <id>` | El tweet se eliminó, está protegido o el ID es incorrecto |
| **404** | `Could not resolve userId for @<handle>` | El nombre de usuario no existe, cambió o corresponde a una cuenta suspendida |
| **404** | `Could not find user with ID: <id>` | Revisa el ID del usuario |
| **400** | `Missing required query param: <x>` | Proporciona el parámetro obligatorio |
| **429** | Límite de solicitudes | Espera `retry_after` y luego reintenta |

:::info
**Contenido restringido por región.** Las restricciones de acceso de X pueden depender de la ubicación, incluida la ubicación de salida de un proxy que hayas proporcionado. Revisa la respuesta y la disponibilidad de la cuenta de destino; no supongas que el acceso mediante la API permite eludir las restricciones regionales.
:::

## 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](/es/api-reference/article-endpoints/article-create-draft-x-articles-draft-post) para conservar `article_id` y reintentar solo el paso que falló.

| Estado | Mensaje | Qué hacer |
| --- | --- | --- |
| **403** | Se requiere Premium | Para publicar artículos necesitas una cuenta de X Premium |
| **404** | Artículo no encontrado | Revisa el ID del artículo |
| **401** | `auth_token` no válido | Renueva las credenciales de sesión de X |
| **400** | Contenido no válido | Corrige el cuerpo del artículo |

## Guía de reintentos

| Si ves… | ¿Reintentar? | Notas |
| --- | --- | --- |
| **429** | ✅ después de la espera indicada | Respeta tanto los límites diarios de la cuenta como los límites de solicitudes |
| **422** | ❌ | Corrige los campos indicados en la respuesta de validación |
| **500 / 502 / 503** | ✅ | Error temporal; reintenta en breve |
| **Código de X 226** | Después de comprobar el resultado de la escritura | Aumenta la espera; revisa las restricciones de la cuenta antes de reintentar |
| **401** | ❌ | Corrige tu clave de API o renueva las credenciales de sesión de X |
| **403** (cuenta suspendida/bloqueada) | ❌ | Usa otra cuenta o desbloquéala primero |
| **404** | ❌ | Revisa el ID o nombre de usuario |
| **400 / 409** | ❌ | Corrige la solicitud (parámetros, tamaño del archivo multimedia, texto duplicado) |

**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.

:::warning Reintentos de escritura
Después de un tiempo de espera agotado, una respuesta vacía o un `5xx` en una escritura, revisa la cronología, el historial de mensajes directos o el estado de la interacción antes de volver a enviar la acción. No supongas que una respuesta fallida significa que la acción nunca se ejecutó.
:::

## 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](/es/guides/error-handling) — MCP, SDK y recuperación de la paginación
- [Autenticación](/es/authentication) — claves de API y credenciales de sesión de X
- [Límites de solicitudes](/es/guides/rate-limits) — esperas progresivas y capacidad de procesamiento
- [Descripción general de la API](/es/api-reference/overview) — referencia actual de endpoints