Códigos de respuesta y errores

Códigos de estado HTTP y gestión de errores para X API

La X API usa códigos de estado HTTP estándar. Las solicitudes satisfactorias devuelven códigos 2xx; los errores devuelven códigos 4xx o 5xx con detalles en el cuerpo de la respuesta.

---

​

Códigos de estado HTTP

​

Códigos de éxito

Código	Significado	Descripción
200	OK	Solicitud correcta
201	Creado	Recurso creado (solicitudes POST)
204	Sin contenido	Éxito sin cuerpo de respuesta (solicitudes DELETE)

​

Códigos de error del cliente

Código	Significado	Causas comunes
400	Bad Request	JSON no válido, consulta mal formada, falta de parámetros obligatorios
401	Unauthorized	Credenciales de autenticación no válidas o ausentes
403	Forbidden	Autenticación válida, pero sin permisos para este recurso o acción
404	Not Found	El recurso no existe o se ha eliminado
409	Conflict	El stream no tiene reglas (solo para el stream filtrado)
429	Too Many Requests	Límite de frecuencia o de uso superado

​

Códigos de error del servidor

Code	Meaning	What to do
500	Error interno del servidor	Espera y vuelve a intentarlo; consulta la página de estado
502	Error de puerta de enlace	Espera y vuelve a intentarlo
503	Servicio no disponible	X está sobrecargado; espera y vuelve a intentarlo
504	Tiempo de espera de la puerta de enlace agotado	Espera y vuelve a intentarlo

---

​

Formato de respuesta de error

Las respuestas de error contienen detalles estructurados:

{
  "title": "Invalid Request",
  "detail": "The 'query' parameter is required.",
  "type": "https://api.x.com/2/problems/invalid-request"
}

Campo	Descripción
type	URI que identifica el tipo de error
title	Descripción breve del error
detail	Explicación específica para este error

Pueden aparecer campos adicionales según el tipo de error.

---

​

Tipos de error

Tipo	Descripción
about:blank	Error genérico (consulta el código de estado HTTP)
.../invalid-request	Solicitud mal formada o parámetros no válidos
.../resource-not-found	La Publicación, el usuario u otro recurso no existe
.../not-authorized-for-resource	Sin acceso al contenido privado/protegido
.../client-forbidden	App no inscrita o sin el acceso requerido
.../usage-capped	Límite de uso superado
.../rate-limit-exceeded	Límite de frecuencia superado
.../streaming-connection	Problema de conexión de streaming
.../rule-cap	Demasiadas reglas de stream filtrado
.../invalid-rules	Error de sintaxis en la regla
.../duplicate-rules	La regla ya existe

---

​

Errores parciales

Algunas solicitudes pueden completarse solo parcialmente. Una respuesta 200 puede incluir tanto data como errors:

{
  "data": [
    {"id": "123", "text": "Hello"}
  ],
  "errors": [
    {
      "resource_id": "456",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [456].",
      "type": "https://api.x.com/2/problems/resource-not-found"
    }
  ]
}

Esto sucede cuando se solicitan varios recursos y algunos no están disponibles.

---

​

Solución de problemas comunes

401 No autorizado

Verifica tu autenticación:

• Verifica que estés usando el método de autenticación correcto para el endpoint
• Asegúrate de que las credenciales no se hayan regenerado
• Comprueba el formato del encabezado Authorization
• Para OAuth 1.0a, verifica el cálculo de la firma

Guía de autenticación →

403 Prohibido

Verifica tu acceso:

• Verifica que tu App tenga acceso a este endpoint
• Algunos endpoints requieren una inscripción o aprobación específica
• Los endpoints en contexto de usuario necesitan ámbitos de OAuth apropiados
• El recurso puede ser privado o estar protegido

429 Demasiadas solicitudes

Límite de tasa alcanzado:

• Consulta el encabezado x-rate-limit-reset para saber cuándo reintentar
• Implementa backoff exponencial
• Considera almacenar en caché las respuestas
• Distribuye las solicitudes a lo largo de la ventana de tiempo

Guía de límites de tasa →

400 Solicitud no válida

Corrige tu solicitud:

• Valida la sintaxis JSON
• Comprueba si faltan parámetros obligatorios
• Verifica los tipos de los parámetros (cadenas frente a números)
• Escapa los caracteres especiales en las consultas

Faltan publicaciones esperadas

Comprueba estos factores:

• Las Publicaciones de cuentas protegidas solo son visibles con autorización
• Las Publicaciones eliminadas devuelven 404
• Algunas Publicaciones no están disponibles en ciertas regiones
• Verifica que la sintaxis de la consulta de búsqueda sea correcta

Desconexiones de streams

Gestiona la reconexión:

• Implementa reconexión automática con backoff
• Usa las funciones de recuperación para los datos perdidos
• Comprueba si hay desconexiones por búfer lleno (el Client no consume lo suficientemente rápido)
• Verifica que exista al menos una regla de stream

Guía de streaming →

---

​

Encabezados de límite de frecuencia

Todas las respuestas incluyen información sobre los límites de frecuencia:

x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800

Header	Description
x-rate-limit-limit	Máximo de solicitudes en la ventana actual
x-rate-limit-remaining	Solicitudes restantes
x-rate-limit-reset	Marca de tiempo Unix en la que la ventana se restablece

---

​

Mejores prácticas

Comprueba los códigos de estado

Siempre comprueba el código de estado HTTP antes de procesar el cuerpo de la respuesta.

Gestiona errores parciales

Comprueba el array errors incluso en respuestas 200.

Implementa lógica de reintentos

Utiliza backoff exponencial para errores 429 y 5xx.

Registra los detalles de la solicitud

Incluye el ID de la solicitud y la marca de tiempo para facilitar la depuración.

---

​

Obtener ayuda

Cuando publiques preguntas sobre errores, incluye:

• La URL del endpoint de la API
• Encabezados de la solicitud (oculta las credenciales)
• Respuesta de error completa
• Lo que esperabas que ocurriera
• Pasos que ya has probado

Foro de desarrolladores

Haz preguntas y busca soluciones.

Estado de la API

Comprueba si hay incidencias conocidas.