Códigos de error de la API de Twitter y cómo solucionarlos

#Cómo leer un error de la API de X

Cada llamada fallida a la API oficial de X te devuelve tres cosas: el estado HTTP, un cuerpo JSON y, en la mayoría de los endpoints, encabezados de límite de tasa. El estado dice qué tipo de falla es, el cuerpo dice cuál de las causas de ese tipo te tocó, y los encabezados dicen cuándo se reinicia un límite de tasa.

Los cuerpos de la API v2 de X comparten una misma forma: un title, un detail y un type, una URI bajo https://api.x.com/2/problems/, a veces con un reason como client-not-enrolled. Los endpoints v1.1 más antiguos, y la respuesta de límite de tasa de la documentación v2 de X, usan en cambio un arreglo errors con un code numerado y un message: {"errors": [{"code": 88, "message": "Rate limit exceeded"}]}. Escribe tu código para que se ramifique según type, reason o code, porque X puede reformular el texto para humanos en cualquier momento.

Un 200 también puede traer errores. Cuando una solicitud pide varios posts o usuarios y algunos están eliminados o protegidos, X devuelve en data los que encontró y lista el resto en un arreglo errors con el tipo resource-not-found o not-authorized-for-resource. Revisa si hay errors en cada respuesta, incluidas las exitosas.

Imprime el cuerpo antes de lanzar una excepción. En Python, raise_for_status() muestra solo la línea de estado, y el propio personal de X pide a los desarrolladores en su foro que impriman response.text, porque el cuerpo nombra el parámetro o el ajuste que falla.

#Estados de la API de X y cómo solucionar cada uno

La API oficial de X responde con once estados de error: cinco de ellos (429, 500, 502, 503 y 504) se resuelven si esperas y reintentas, y los otros seis vuelven a fallar hasta que cambies la solicitud, las claves, el saldo o el acceso. La referencia de códigos de respuesta (se abre en una pestaña nueva) de X lista diez de ellos; el 402 es el que omite.

• 400 Bad Request

  Qué significa en la API oficial de X

  Falta un parámetro, está mal formado o fuera de rango; el arreglo errors del cuerpo lo nombra

  Solución

  Corrige el parámetro que nombra el cuerpo

  ¿Reintentar?

  No

• 401 Unauthorized

  Qué significa en la API oficial de X

  X no puede verificar quién llama: claves incorrectas o revocadas, método de autenticación equivocado, firma OAuth 1.0a inválida

  Solución

  Regenera las claves, usa la autenticación que indica el endpoint, sincroniza el reloj

  ¿Reintentar?

  No

• 402 Payment Required

  Qué significa en la API oficial de X

  El saldo prepagado de pago por uso está vacío: tipo credits-depleted

  Solución

  Agrega créditos o usa las claves de la app con fondos

  ¿Reintentar?

  No

• 403 Forbidden

  Qué significa en la API oficial de X

  Las claves funcionan, pero esta app, token o cuenta no puede hacer esto

  Solución

  Lee el reason o el code: inscripción, permisos, nivel de acceso

  ¿Reintentar?

  No

• 404 Not Found

  Qué significa en la API oficial de X

  El post, el usuario o la URL no existe, o el post fue eliminado

  Solución

  Revisa el ID y la ruta del endpoint

  ¿Reintentar?

  No

• 409 Conflict

  Qué significa en la API oficial de X

  Un stream filtrado no tiene reglas

  Solución

  Agrega una regla y luego conéctate

  ¿Reintentar?

  No

• 429 Too Many Requests

  Qué significa en la API oficial de X

  Se agotó una ventana de límite de tasa (código 88) o se alcanzó el tope mensual de uso (usage-capped)

  Solución

  Espera a x-rate-limit-reset; un tope de uso espera al siguiente ciclo de facturación

  ¿Reintentar?

  En el reinicio

• 500 Internal Server Error

  Qué significa en la API oficial de X

  Una falla dentro de X (código 131)

  Solución

  Reintenta con una pausa creciente

  ¿Reintentar?

  Sí

• 502 Bad Gateway

  Qué significa en la API oficial de X

  Los servidores frontales de X no obtuvieron respuesta del servicio que tienen detrás

  Solución

  Reintenta con una pausa creciente

  ¿Reintentar?

  Sí

• 503 Service Unavailable

  Qué significa en la API oficial de X

  X está sobre su capacidad (código 130)

  Solución

  Reintenta con una pausa creciente

  ¿Reintentar?

  Sí

• 504 Gateway Timeout

  Qué significa en la API oficial de X

  Los servidores de X agotaron el tiempo de espera de la solicitud

  Solución

  Reintenta con una pausa creciente y pide menos por llamada

  ¿Reintentar?

  Sí

#402 Payment Required: créditos de la API de X agotados

Un 402 de la API oficial de X significa que el saldo prepagado detrás de tu app ya no tiene nada que gastar, así que X rechaza toda llamada facturable hasta que lleguen créditos. El modelo de pago por uso de X cobra cada lectura por adelantado, $0.005 por post y $0.010 por usuario según la lista de precios de X (se abre en una pestaña nueva), y los desarrolladores nuevos no han tenido otra vía de entrada desde el 6 de febrero de 2026.

Este es el cuerpo, tal como lo publicó un desarrollador en el foro de X en octubre de 2026:

{
  "title": "Payment Required",
  "detail": "credits depleted",
  "type": "https://api.x.com/2/problems/credits-depleted"
}

El enlace de type no lleva a nada útil: la referencia de errores de X no tiene entrada para el 402, un vacío que un desarrollador reportó en el foro de X (se abre en una pestaña nueva) en julio de 2026. Las causas, de la más común a la menos común:

• El saldo está en cero o justo por debajo. Una solicitud puede dejar un pequeño remanente negativo, y X bloquea las llamadas hasta que créditos nuevos lo cubran. Compra créditos en la Developer Console; la recarga automática no se ejecuta mientras el saldo sea cero o negativo.
• Se agotó el límite de gasto del ciclo. Un límite que fijas en la consola es lo máximo que gastará tu cuenta en un ciclo de facturación. Súbelo o espera al siguiente ciclo.
• Las claves pertenecen a otra app. Si el Client ID, el secret o el Bearer token vienen de una app de otro Project o de una cuenta de desarrollador anterior, toda llamada facturable falla aunque la consola muestre dinero. El 402 de un desarrollador con $20 de saldo (se abre en una pestaña nueva) terminó justo ahí en octubre de 2026. Copia las claves de la app con fondos y autoriza de nuevo. Que GET /2/users/me funcione solo prueba que la autenticación pasa.
• Las ráfagas vacían el saldo más rápido de lo que la recarga automática lo llena. La página de precios de X advierte que un uso capaz de vaciar una recarga en 5 minutos aún puede quedarse sin créditos. Sube el monto de recarga.

Para tener en cuenta

Un 402 y un 429 de tipo usage-capped detienen ambos las lecturas de pago, por razones distintas. El 402 es dinero: agrega créditos y la siguiente llamada funciona. El tope de uso es volumen: el pago por uso se detiene en 3 millones de lecturas de posts por ciclo de facturación, y pasado ese punto solo el siguiente ciclo o un contrato Enterprise, desde unos $42K al mes, devuelve las lecturas.

#403 Forbidden, 453 y otros errores de acceso

Un 403 significa que X aceptó tus claves y rechazó la acción, y el reason o el code numerado del cuerpo te dice qué puerta está cerrada; un reintento nunca la abre. Los seis que más verás:

• client-not-enrolled (tipo client-forbidden): las claves vienen de una app que no está asociada a un Project, o que no está inscrita en el acceso que necesita el endpoint. En la Developer Console, coloca la app dentro de un Project de pago por uso y usa las claves de esa app, como aconsejó el personal de X en un hilo de octubre de 2026 (se abre en una pestaña nueva).
• 453: "You currently have access to a subset of X API v2 endpoints and limited v1.1 endpoints (e.g. media post, oauth) only." La llamada fue a un endpoint v1.1 distinto de la carga de medios o de OAuth, que es lo que hacen tweepy.API y otros clientes más antiguos. Llama en su lugar al endpoint v2: tweepy.Client en Python, el paquete twitter-api-v2 en Node.js.
• 261, "Your App cannot perform write actions": la app está configurada como Read only. Cámbiala a Read and Write y luego regenera los tokens de acceso, porque los tokens viejos conservan el permiso con el que se crearon.
• Cuentas protegidas o suspendidas: el código 179 o el tipo not-authorized-for-resource para un post protegido, el 63 para un usuario suspendido. Nada de tu lado las abre; omite el elemento.
• 326, bloqueada temporalmente: la cuenta detrás del token activó los controles antispam de X. Inicia sesión en x.com y completa la verificación que muestre X.
• 226 y 187 en escrituras: el filtro antispam de X o un post duplicado. El mensaje 226 tiene sus propias soluciones en nuestra guía sobre por qué X dice que una solicitud parece automatizada.

Los likes, los follows y las citas de posts también salieron del acceso de autoservicio el 20 de abril de 2026, así que esas escrituras ahora terminan en un 403 en una app de pago por uso. Cada texto de 403, con los pasos en la consola para cada uno, está en nuestra guía de API de X 403 Forbidden.

#429 y 5xx: los errores que se arreglan esperando

Un 429 o un 5xx es el único tipo de error de la API de X que un reintento puede arreglar, y solo en el momento correcto: la hora de reinicio para un 429, una pausa creciente para un 5xx.

Un 429 con código 88 significa que a la ventana de un endpoint no le quedan solicitudes. Tres encabezados en cada respuesta muestran dónde estás, x-rate-limit-limit, x-rate-limit-remaining y x-rate-limit-reset, un tiempo Unix en segundos; la mayoría de las ventanas duran 15 minutos. Un 429 de tipo usage-capped es el tope mensual de 3 millones de lecturas de posts, y el encabezado de reinicio no lo levanta. Cuánto dura cada límite, en la app de X y en la API, se explica en nuestra guía de Twitter rate limit exceeded.

Un 5xx es una falla del lado de X: 500 y el código 131 son errores internos, 503 y el código 130 indican sobrecapacidad, 502 y 504 son tiempos de espera entre servidores de X. Espera 1, 2, 4 y 8 segundos entre intentos, y luego detente y registra el cuerpo.

Este manejador reintenta solo lo que puede funcionar y se detiene ante todo lo demás, con el cuerpo en el mensaje:

import time
import requests

RETRY = {500, 502, 503, 504}

def call_x(url, headers, params=None, tries=5):
    for attempt in range(tries):
        r = requests.get(url, headers=headers, params=params, timeout=30)
        if r.ok:
            body = r.json()
            for err in body.get("errors", []):  # partial errors in a 200
                print("skipped:", err.get("detail"))
            return body
        if r.status_code == 429 and "usage-capped" not in r.text:
            reset = int(r.headers.get("x-rate-limit-reset", time.time() + 60))
            time.sleep(max(reset - time.time(), 1) + 1)
        elif r.status_code in RETRY:
            time.sleep(2 ** attempt)
        else:  # 400-409 and a capped 429: fix the cause first
            raise RuntimeError(f"X API {r.status_code}: {r.text}")
    raise RuntimeError(f"X API still failing after {tries} tries")

#Códigos de error de la API de X por número

Los códigos numerados vienen de la API v1.1 y siguen llegando hoy: en respuestas v1.1, en tracebacks de Tweepy y en algunos cuerpos v2, como el código 88 en una llamada con límite de tasa. Los mensajes y estados de abajo son los propios de X, de su última tabla de códigos publicada (archivada en mayo de 2023 (se abre en una pestaña nueva)); el 453 proviene de reportes de desarrolladores en el foro de X. Un código que no esté aquí vuelve a su estado en la tabla de arriba.

• 32

  Mensaje de X

  Could not authenticate you.

  Estado

  401

  Causa y solución

  Claves, token o firma OAuth incorrectos: regenera y firma de nuevo

• 34

  Mensaje de X

  Sorry, that page does not exist.

  Estado

  404

  Causa y solución

  URL de endpoint o ID incorrectos

• 50

  Mensaje de X

  User not found.

  Estado

  404

  Causa y solución

  La cuenta fue eliminada o renombrada: búscala por ID de usuario

• 63

  Mensaje de X

  User has been suspended.

  Estado

  403

  Causa y solución

  La cuenta que consultaste está suspendida: omítela

• 64

  Mensaje de X

  Your account is suspended and is not permitted to access this feature.

  Estado

  403

  Causa y solución

  La cuenta del propio token está suspendida: apela ante X

• 87

  Mensaje de X

  Client is not permitted to perform this action.

  Estado

  403

  Causa y solución

  El endpoint no está abierto a esta app

• 88

  Mensaje de X

  Rate limit exceeded.

  Estado

  429

  Causa y solución

  Espera a x-rate-limit-reset

• 89

  Mensaje de X

  Invalid or expired token.

  Estado

  401 o 403

  Causa y solución

  Token revocado o vencido: autoriza de nuevo y guarda el token nuevo

• 92

  Mensaje de X

  SSL is required.

  Estado

  403

  Causa y solución

  Llama por HTTPS con TLS 1.2

• 99

  Mensaje de X

  Unable to verify your credentials.

  Estado

  403

  Causa y solución

  Consumer secret o token secret incorrecto

• 130

  Mensaje de X

  Over capacity.

  Estado

  503

  Causa y solución

  Reintenta con una pausa creciente

• 131

  Mensaje de X

  Internal error.

  Estado

  500

  Causa y solución

  Reintenta con una pausa creciente

• 135

  Mensaje de X

  Could not authenticate you.

  Estado

  401

  Causa y solución

  El desfase del reloj rompió la marca de tiempo de OAuth: sincroniza el reloj

• 144

  Mensaje de X

  No status found with that ID.

  Estado

  404

  Causa y solución

  El post fue eliminado o el ID es incorrecto

• 179

  Mensaje de X

  Sorry, you are not authorized to see this status.

  Estado

  403

  Causa y solución

  El autor protege sus posts

• 185

  Mensaje de X

  User is over daily status update limit.

  Estado

  403

  Causa y solución

  Se agotó el tope de publicación de la cuenta: espera unas horas

• 186

  Mensaje de X

  Tweet needs to be a bit shorter.

  Estado

  403

  Causa y solución

  El texto supera el límite de longitud

• 187

  Mensaje de X

  Status is a duplicate.

  Estado

  403

  Causa y solución

  El mismo texto ya se publicó: cámbialo

• 215

  Mensaje de X

  Bad authentication data.

  Estado

  400

  Causa y solución

  Falta el encabezado Authorization o está mal formado

• 220

  Mensaje de X

  Your credentials do not allow access to this resource.

  Estado

  403

  Causa y solución

  El token está restringido: usa uno con el alcance necesario

• 226

  Mensaje de X

  This request looks like it might be automated.

  Estado

  403

  Causa y solución

  El filtro antispam de X detuvo una escritura: baja el ritmo

• 261

  Mensaje de X

  Your App cannot perform write actions.

  Estado

  403

  Causa y solución

  App de solo lectura: configura Read and Write y regenera los tokens

• 326

  Mensaje de X

  ...this account is temporarily locked.

  Estado

  403

  Causa y solución

  Inicia sesión en x.com y quita el bloqueo

• 327

  Mensaje de X

  You have already retweeted this Tweet.

  Estado

  403

  Causa y solución

  Ya está hecho: trátalo como éxito

• 349

  Mensaje de X

  You cannot send messages to this user.

  Estado

  403

  Causa y solución

  El destinatario no acepta tus mensajes

• 415

  Mensaje de X

  Callback URL not approved for this client App.

  Estado

  403

  Causa y solución

  Agrega la URL de callback exacta a los ajustes de la app

• 453

  Mensaje de X

  You currently have access to a subset of X API v2 endpoints...

  Estado

  403

  Causa y solución

  Una llamada v1.1 o falta un nivel de acceso: llama al endpoint v2

#Tipos de problema de la API v2 de X

En las respuestas v2, el campo type lleva la causa: uno de los once tipos que X documenta, más credits-depleted, que no documenta. Todas las URI empiezan con https://api.x.com/2/problems/.

• invalid-request

  Qué significa

  Un 400: un parámetro es incorrecto, listado en errors

  Solución

  Corrige ese parámetro

• resource-not-found

  Qué significa

  El post o el usuario no existe, a menudo dentro de un 200

  Solución

  Omítelo o revisa el ID

• not-authorized-for-resource

  Qué significa

  Contenido protegido o privado

  Solución

  Omítelo

• client-forbidden

  Qué significa

  Un 403 con un reason, normalmente client-not-enrolled

  Solución

  Mueve la app a un Project

• credits-depleted

  Qué significa

  Un 402: el saldo prepagado está vacío

  Solución

  Agrega créditos

• usage-capped

  Qué significa

  Un 429: el tope mensual de uso

  Solución

  Espera al siguiente ciclo de facturación

• rate-limit-exceeded

  Qué significa

  Un 429: una ventana de límite de tasa

  Solución

  Espera a x-rate-limit-reset

• streaming-connection

  Qué significa

  Un problema de conexión del stream

  Solución

  Reconéctate con una pausa creciente

• rule-cap, invalid-rules, duplicate-rules

  Qué significa

  Reglas de stream filtrado: demasiadas, sintaxis incorrecta, ya existen

  Solución

  Elimina, corrige u omite la regla

• about:blank

  Qué significa

  Un error genérico

  Solución

  Lee el estado

El arreglo errors de un 400 nombra el valor exacto que X rechazó. En este caso de octubre de 2026 del foro de X, la búsqueda en el archivo completo rechazó un end_time fijado en el momento de la solicitud:

{
  "title": "Invalid Request",
  "detail": "One or more parameters to your request was invalid.",
  "type": "https://api.x.com/2/problems/invalid-request",
  "errors": [
    {
      "message": "Invalid 'end_time':'2026-10-20T08:04Z'. 'end_time' must be a minimum of 10 seconds prior to the request time.",
      "parameters": { "end_time": ["2026-10-20T08:04Z"] }
    }
  ]
}

La solución que dio el personal de X: fija end_time al menos 10 segundos en el pasado, o no lo incluyas.

#Lee datos públicos de X con una sola clave API: Sorsa API

Si tus llamadas fallidas solo leen datos públicos, Sorsa API, una API y scraper de Twitter (X), te quita de encima la mayor parte de esta página. Necesita una sola clave API en un encabezado ApiKey y ninguna cuenta de desarrollador de X, app, Project ni OAuth, así que los errores de firma 401, client-not-enrolled, 453 y 402 nunca se aplican. Tu propia cuenta de X tampoco interviene nunca.

Sorsa API devuelve cada error con una sola forma de cuerpo, {"message": "..."}, y estos son los estados que verás:

• 400

  En Sorsa API

  Falta un parámetro o está mal formado

  Solución

  Corrige el parámetro

• 401

  En Sorsa API

  invalid api key

  Solución

  Vuelve a copiar la clave desde el panel

• 403

  En Sorsa API

  missing key in request header, o se agotaron las solicitudes de la clave

  Solución

  Envía el encabezado ApiKey; recarga o mejora tu plan

• 404

  En Sorsa API

  El post o la cuenta no existe o es protegida

  Solución

  Revisa el ID

• 429

  En Sorsa API

  Más de 20 solicitudes en un segundo

  Solución

  Espera un segundo

• 500

  En Sorsa API

  Una falla de nuestro lado

  Solución

  Reintenta tras 1 a 2 segundos

Enviamos los errores de clave a la API en vivo el 2 de noviembre de 2026. Un encabezado escrito Api-Key en lugar de ApiKey cuenta como ninguna clave, y la llamada devuelve 403:

curl "https://api.sorsa.io/v3/info?username=error_codes_demo_acct" \
  -H "Api-Key: YOUR_API_KEY"

{"message": "missing key in request header"}

Con el encabezado correcto y una clave equivocada, la misma llamada devuelve 401 y {"message": "invalid api key"}. Las solicitudes fallidas nunca se cobran, y la página de códigos de error de Sorsa API (se abre en una pestaña nueva) en la documentación lista cada estado con sus causas.

1. Obtén una clave. Regístrate y copia tu clave API del panel. Las primeras 100 solicitudes son gratis.

2. Lee hasta 100 posts en una solicitud. POST /tweet-info-bulk (se abre en una pestaña nueva) recibe enlaces o IDs de posts y devuelve cada post con el perfil completo de su autor.

   curl -X POST "https://api.sorsa.io/v3/tweet-info-bulk" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tweet_links": ["2117203385470271488", "2117199027635167232"]}'
   

   {
     "tweets": [
       {
         "id": "2117203385470271488",
         "full_text": "Two layers in every error: status, then cause.",
         "created_at": "2026-11-02T09:12:44Z",
         "lang": "en",
         "likes_count": 41,
         "retweet_count": 6,
         "reply_count": 3,
         "view_count": 5210,
         "user": {
           "id": "1592041833471827968",
           "username": "error_codes_demo_acct",
           "display_name": "Error Codes Demo",
           "followers_count": 1840
         }
       },
       {
         "id": "2117199027635167232",
         "full_text": "Retry 429 and 5xx. Fix everything else first.",
         "created_at": "2026-11-02T08:55:20Z",
         "lang": "en",
         "likes_count": 27,
         "retweet_count": 4,
         "reply_count": 2,
         "view_count": 3380,
         "user": {
           "id": "1592041833471827968",
           "username": "error_codes_demo_acct",
           "display_name": "Error Codes Demo",
           "followers_count": 1840
         }
       }
     ]
   }
   

   Ver respuesta completa

3. Consulta perfiles de la misma forma. GET /info (se abre en una pestaña nueva) devuelve un perfil por username, user_id o user_link, y un 404 significa que la cuenta ya no existe o es protegida.

4. Vigila el saldo. GET /key-usage-info (se abre en una pestaña nueva) devuelve las solicitudes que quedan y la fecha en que se renuevan; la consulta en sí es gratis. Reintenta un 429 tras un segundo y trata un 403 con una clave válida como la señal para recargar.

Leer posts por ID cuesta desde $0.014 por 1,000 en Sorsa API, 100 posts por solicitud, frente a $5.00 por 1,000 en la API oficial de X, cuyo plan de pago por uso además se detiene en 3 millones de lecturas de posts al mes:

A partir del 22 de noviembre de 2026, la API oficial de X también factura el perfil del autor que viene con cada post, $0.010 por usuario (aviso de X (se abre en una pestaña nueva)); cada post de Sorsa API trae el perfil completo de su autor en la misma solicitud. Sorsa API solo lee: para publicar, dar like o enviar mensajes, conserva la API oficial de X para esas llamadas.

#Corrige el error que tienes enfrente y luego mueve tus lecturas

Casi todo error de la API de X se resuelve de una de dos formas: esperar en un 429 o un 5xx, o cambiar la solicitud, las claves, el saldo o el acceso de la app en cualquier otro caso. Si tus errores vienen de leer posts, perfiles o seguidores públicos, pasa esas lecturas a Sorsa API: una sola clave API, mensajes de error claros, 20 solicitudes por segundo en todos los planes y posts desde $0.014 por 1,000, con 100 solicitudes gratis para probarlo hoy.

#Preguntas frecuentes