Códigos de respuesta y errores

La X API ofrece los siguientes códigos de respuesta y error para ayudar a comprender y depurar en el momento. Usa la guía de depuración y el índice de errores a continuación para obtener más contexto.

Las respuestas correctas se indican con un código HTTP de la serie 200 y una carga útil en formato JSON que contiene los objetos solicitados, creados, modificados o eliminados, junto con una indicación de cómo el servidor interpretó tu solicitud.

Las respuestas de error se devuelven con un código HTTP fuera de la serie 200. Los distintos códigos de error señalan diferentes causas del error. La X API intenta devolver códigos de estado HTTP apropiados para cada solicitud.

​

Códigos de estado HTTP de X API v2

Código	Texto	Descripción	Consejos para la resolución de problemas
200	OK	La solicitud se completó correctamente.
400	Bad Request	La solicitud no es válida o no puede procesarse. Un mensaje de error adjunto ofrecerá más detalles. Las solicitudes sin autenticación o con parámetros de consulta no válidos se consideran inválidas y generarán esta respuesta.	Verifica el formato de tu consulta JSON. Por ejemplo, si tu regla contiene comillas dobles asociadas a una coincidencia exacta u otro operador, quizá debas escaparlas con una barra invertida para distinguirlas de la estructura del formato JSON.
401	Unauthorized	Hubo un problema al autenticar tu solicitud. Puede deberse a credenciales de autenticación faltantes o incorrectas. También puede devolverse en otras circunstancias no definidas.	Verifica que estés usando el método de autenticación correcto y que tus credenciales sean válidas.
403	Forbidden	La solicitud se entiende, pero se rechazó o no se permite el acceso. Un mensaje de error adjunto explicará el motivo.	Verifica que tu cuenta de desarrollador incluya acceso al endpoint que intentas usar. También puede que necesites que tu App se incluya en una lista de permitidos (p. ej., Engagement API o Ads API) o registrarte para obtener acceso.
404	Not Found	El URI solicitado no es válido o el recurso solicitado, como un usuario, no existe.	Verifica que estés usando parámetros válidos y el URI correcto para el endpoint que estás utilizando.
409	Connection Exception	Se devuelve al intentar conectarse a un stream filtrado que no tiene reglas.	Verifica que hayas creado al menos una regla en el stream al que te estás conectando. Un stream filtrado solo devolverá Posts que coincidan con una regla activa. Si no hay reglas, el stream no devolverá ningún Post.
429	Too Many Requests	Se devuelve cuando una solicitud no puede atenderse porque se agotó el límite de tasa de la App o el límite de Posts. Consulta Rate Limiting.	Verifica la cantidad de solicitudes por intervalo permitidas con el endpoint que estás usando. Espera a que el intervalo se restablezca. Espacia tus solicitudes para evitar alcanzar los límites de tasa o actualiza al siguiente plan de datos disponible.
500	Internal Server Error	Algo está fallando. Por lo general, es un error temporal, por ejemplo, en una situación de alta carga o si un endpoint tiene problemas temporalmente.	Consulta la página de estado de X API o el foro de la comunidad de desarrolladores por si otros tienen problemas similares, o simplemente espera e inténtalo de nuevo más tarde.
501	Unimplemented	X API no admite este endpoint y no puede cumplir la solicitud.
503	Service Unavailable	Los servidores de X están activos, pero sobrecargados de solicitudes. Inténtalo de nuevo más tarde.	Consulta la página de estado de X API o el foro de la comunidad de desarrolladores por si otros tienen problemas similares, o simplemente espera e inténtalo de nuevo más tarde.

Cuando se produce un error durante una solicitud, se devuelve información detallada sobre el error en el cuerpo de la respuesta para ayudar a diagnosticar el problema. Un campo type, que es un URI, indica la naturaleza del problema, mientras que los campos adicionales proporcionan más detalles. Los campos type, title y detail siempre se devolverán en estos cuerpos (consulta la tabla a continuación). Cualquier campo adicional, como en el ejemplo a continuación, variará según el tipo de error.

{
  "client_id": "101010101",
  "required_enrollment": "Básico Estándar",
  "registration_url": "https://developer.twitter.com/en/account",
  "title": "Cliente no autorizado",
  "detail": "Esta solicitud debe realizarse con una cuenta de desarrollador aprobada que esté registrada en el endpoint solicitado. Obtén más información en nuestra documentación.",
  "reason": "cliente-no-registrado",
  "type": "https://api.x.com/2/problems/client-forbidden"
}

​

Errores parciales

En algunos casos, puede ver los errores detallados arriba en una respuesta que devuelve un código de estado 200. En esos casos, el endpoint está diseñado para devolver los datos que pueda y, al mismo tiempo, proporcionar errores detallados sobre lo que no pudo devolver.

Por ejemplo, el endpoint de búsqueda de Posts permite que una App de desarrollador de X solicite más de un id. Si algunos de esos Posts están disponibles, pero uno de ellos ha sido eliminado, los Posts disponibles se devolverían en el campo data de la respuesta. Se devolvería un campo errors adicional en el payload, indicando qué Post(s) solicitados no se pudieron devolver. Se emplea el mismo formato que en los errores de solicitud completa para facilitar el diagnóstico de problemas.

​

Información sobre errores

Cada tipo de problema indica la naturaleza del problema encontrado. También puedes consultar una lista completa de problemas que podrías encontrar en nuestra especificación de la API.

La X API intenta devolver códigos de estado HTTP adecuados para cada solicitud.

Título	Tipo	Descripción
Problema genérico	about:blank	Un problema genérico sin información adicional más allá de la proporcionada por el código de estado HTTP.
Problema de solicitud no válida	https://api.X.com/2/problems/invalid-request	Un problema que indica que esta solicitud no es válida. Si tu solicitud incluye un cuerpo POST, asegúrate de que el contenido sea JSON válido y cumpla con la especificación OpenAPI.
Problema de recurso no encontrado	https://api.X.com/2/problems/resource-not-found	Un problema que indica que un Post, Usuario, etc., no existe.
Problema de recurso no autorizado	https://api.X.com/2/problems/not-authorized-for-resource	Un problema que indica que no tienes permiso para ver un Post, Usuario, etc., en particular.
Problema de cliente prohibido	https://api.X.com/2/problems/client-forbidden	Un problema que indica que tu cliente tiene prohibido realizar esta solicitud.
Problema de recurso no permitido	https://api.X.com/2/problems/disallowed-resource	Un problema que indica que el recurso solicitado infringe los preceptos de esta API.
Problema de autenticación no admitida	https://api.X.com/2/problems/unsupported-authentication	Un problema que indica que la autenticación utilizada no es compatible.
Problema de límite de uso alcanzado	https://api.X.com/2/problems/usage-capped	Un problema que indica que se ha superado un límite de uso.
Problema de excepción de conexión	https://api.X.com/2/problems/streaming-connection	Un problema que indica que hay un problema con la conexión.
Problema de cliente desconectado	https://api.X.com/2/problems/client-disconnected	Tu cliente se ha desconectado.
Problema de desconexión operativa	https://api.X.com/2/problems/operational-disconnect	Has sido desconectado por motivos operativos.
Problema de límite de reglas	https://api.X.com/2/problems/rule-cap	Has superado el número máximo de reglas.
Problema de longitud de regla	https://api.X.com/2/problems/rule-length	Has superado el número máximo de caracteres permitidos en tu consulta o regla según tu nivel de acceso. Consulta los niveles de acceso.
Problema de reglas no válidas	https://api.X.com/2/problems/invalid-rules	La regla que has enviado no es válida.
Problema de reglas duplicadas	https://api.X.com/2/problems/duplicate-rules	La regla que has enviado es un duplicado.

​

Consejos para resolver problemas

Depuración de tu código

Al crear una aplicación, es normal encontrarse con errores o situaciones inesperadas de vez en cuando. A continuación, encontrarás algunos consejos para depurar tu código:

Empieza desglosando el problema en partes más pequeñas para identificar dónde está la causa. Por ejemplo, si estás integrando un endpoint REST o de streaming, el problema podría deberse a cualquiera de los siguientes aspectos:

• El endpoint requiere la autenticación adecuada.
• El endpoint requiere parámetros y encabezados válidos. Cualquier regla de filtrado debe construirse con los operadores correctos y la sintaxis adecuada.
• El URI del endpoint debe ser correcto y, en el caso de endpoints REST, se debe usar el método HTTP correcto.
• Es posible que los datos o el recurso a los que intentas acceder no estén disponibles para ti (por ejemplo, los datos privados solo están disponibles para usuarios autenticados).
• Tu paquete de datos actual te da acceso únicamente a ciertos endpoints y a límites de frecuencia específicos. Consulta tu Portal de desarrolladores para más detalles.
• Tu código utiliza una biblioteca de terceros para integrar el endpoint en tu código.
• Tu código debe poder analizar correctamente la respuesta del endpoint.

Lee el mensaje de error que acompaña a la respuesta. Esto debería darte una buena indicación del problema. Usa las tablas de la sección de códigos de error y respuesta para obtener consejos de solución específicos para cada código de error.

Para endpoints REST, puedes usar un cliente REST como Postman o Insomnia para validar los pasos (1) a (5) anteriores (consulta nuestra guía “Primeros pasos con Postman”). Si la solicitud con el cliente REST devuelve un código de estado 200 (éxito), puedes asumir que el problema está en tu código o en la biblioteca que estás usando; no en la solicitud al endpoint en sí.

Para endpoints de streaming, puedes usar cURL (una herramienta de línea de comandos para enviar u obtener solicitudes utilizando la sintaxis de URL) para comprobar si el problema está en la solicitud al endpoint (pasos (1) a (5) anteriores) o en tu propio código (pasos (6) a (7) anteriores).

Problemas de autenticación

• Verifica que estés utilizando el método de autenticación adecuado requerido para el endpoint. Puedes identificarlo en la página de referencia del API del endpoint.
• Verifica que tus credenciales de autenticación sean correctas. Puedes revisar o regenerar las claves y los tokens de tu App en la sección Apps de tu panel de desarrollador (en “Details”).
• Verifica que hayas autorizado correctamente tu solicitud OAuth 1.0a con oauth_nonce, oauth_signature y oauth_timestamp.
• Si el problema persiste, considera usar una biblioteca de OAuth, un cliente REST como Postman o Insomnia, o xurl.

Consulta nuestra guía sobre autenticación para obtener más información sobre todo lo anterior.

Problemas de limitación de solicitudes y límites de Posts

Puede aparecer un error 429 si alcanzas un límite de solicitudes para un endpoint determinado o si llegas al límite de Posts.

Si se devuelve el error específico “Too many requests”, alcanzaste el límite de solicitudes del endpoint. Es decir, superaste el número máximo de solicitudes permitidas para un endpoint en un período de tiempo determinado.

Ten en cuenta que los límites se establecen a nivel de App y a nivel de usuario.

• Nivel de App de X indica el número de solicitudes permitidas cuando se usa OAuth 2.0 App-Only, donde los límites se determinan de forma global para toda la App. Por ejemplo, si un método permite 15 solicitudes por ventana de límite, entonces permite realizar 15 solicitudes por ventana en nombre de tu App de X. Este límite se considera completamente por separado del límite a nivel de usuario. Lee más en nuestra guía sobre OAuth 2.0 App-Only.
• Nivel de contexto de usuario indica el número de solicitudes que se pueden realizar por Access Token de usuario cuando se utiliza Contexto de usuario de OAuth 1.0a o Código de autorización de OAuth 2.0 con PKCE. Por ejemplo, si un método permite 15 solicitudes por ventana de límite, entonces permite 15 solicitudes por ventana y por Access Token de usuario. Lee más en nuestra guía sobre cómo obtener los Access Tokens de un usuario con OAuth 1.0a y OAuth 2.0.

Comienza por comprobar los límites del endpoint que estás usando. Puedes encontrar esta información en la página de referencia del API del endpoint y en el nuevo panel del Portal de desarrolladores.

Consulta nuestra documentación para obtener información adicional sobre límites, incluido cómo usar encabezados HTTP para rastrear la posición de tu App respecto de un límite dado, cómo recuperarte de un error 429 por límite y consejos para evitar ser limitado en primer lugar:

• Límites para endpoints v2

Si recibiste el error específico “Usage cap exceeded: Monthly product cap”, significa que alcanzaste el límite de Posts para tu nivel de acceso. Encontrarás más detalles sobre estos límites de Posts en nuestra página de documentación.

Problemas de Posts faltantes

Sigue los pasos a continuación si esperabas que se devolviera un Post, pero el endpoint no lo entregó.

• Revisa tu regla para asegurarte de que estás usando los operadores y la sintaxis correctos. Divide la regla en cláusulas más pequeñas para confirmar que la sintaxis sea correcta.
• Si la cuenta desde la cual se envió el Post estaba protegida en el momento en que se creó el Post, el Post no se devolverá, incluso si la cuenta es pública en el momento de la solicitud al endpoint. Por lo general, puedes comprobar esto usando X Advanced Search: si un Post no aparece usando la funcionalidad de X Advanced Search, debes asumir que no será devuelto por el endpoint.

Los siguientes pasos aplican solo a endpoints de streaming:

• ¿Estabas conectado al stream cuando se envió el Post? Recuerda que la marca de tiempo entregada en el objeto Post indica la hora en UTC. Si sufriste una desconexión cuando se envió el Post, revisa las funciones de recuperación y redundancia disponibles para reponer cualquier data perdida.
• ¿Tu regla estaba activa cuando se envió el Post? Recuerda que la marca de tiempo entregada en el objeto Post indica la hora en UTC.

Problemas de desconexión por búfer lleno

Es posible que reciba uno de los siguientes errores cuando su flujo no mantiene el ritmo de la velocidad a la que entregamos datos y su App no consume los datos del flujo con la suficiente rapidez:

This stream has been disconnected because your client was unable to keep up with us.

This stream has been disconnected for operational reasons.

Permitimos que la entrega se atrase durante un período y contamos con un búfer temporal de preparación para cada flujo de nuestro lado; pero si no logra ponerse al día, iniciamos una desconexión para permitirle reconectarse en el punto temporal actual. Tenga en cuenta que esto puede provocar pérdida de datos (para los datos que estén dentro del búfer en el momento de la desconexión por búfer lleno).

Esto puede ocurrir en torno a grandes picos de datos. En general, recomendamos usar un proceso de búfer para consumir datos rápidamente que esté separado del proceso de procesamiento.

Si es un cliente Empresarial que usa endpoints v1.1, puede obtener más información sobre cómo optimizar su App para evitar desconexiones como esta en nuestros artículos sobre conexiones y sobre el consumo de datos en streaming aquí y aquí.

Existe una variedad de herramientas disponibles para recuperar Posts perdidos debido a una desconexión, incluidas las que se enumeran a continuación. Tenga en cuenta que las siguientes herramientas solo están disponibles con endpoints v1.1 en el nivel de acceso Empresarial.

• Conexiones redundantes - Con múltiples conexiones, consuma el flujo desde varios servidores para evitar la pérdida de datos cuando uno se desconecte.
• Replay - Recupere datos de los últimos 5 días usando un flujo separado.
• Backfill - Reconcéctese dentro de 5 minutos y reanude desde donde se quedó.
• Historical PowerTrack - Recupere datos de todo el archivo de X.

​

Obtén ayuda

El foro de la comunidad de X está disponible para que realices consultas técnicas sobre la plataforma para desarrolladores de X. Es un foro de debate donde encontrarás preguntas de otros desarrolladores e información técnica sobre diversos temas relacionados con el uso de la X API.

Te invitamos a participar en la conversación respondiendo preguntas y contribuyendo a los debates en nuestro foro. El personal de X también está presente para brindar asistencia.

Foro de la comunidad de X

​

Antes de publicar una pregunta

• Busca en la documentación para desarrolladores de X información relacionada con tu incidencia
• Busca en el foro de la comunidad preguntas similares de otros desarrolladores
• Revisa las directrices del foro de la comunidad

​

Cuando publiques una pregunta, asegúrate de incluir la siguiente información

• Una descripción del problema
• La llamada a la API que se está realizando (incluye los encabezados, si es posible)
• La respuesta de X recibida (incluye cualquier mensaje de error)
• Qué esperabas recibir en su lugar
• Lista de pasos realizados para solucionar el problema
• Lista de pasos necesarios para reproducir el problema
• Si corresponde, el periodo durante el cual ocurrió el problema
• Si corresponde, el App ID, Post ID, etc.
• Cualquier fragmento de código o captura de pantalla relevante

Incluye solo un tema/pregunta por publicación.

Si tienes solicitudes de funciones o comentarios, envíalos a través del X Developer Platform Feedback Form.

Para problemas relacionados con las Políticas, como la suspensión de una App, comunícate con el Policy support.

Para problemas relacionados con X, como el inicio de sesión y el soporte de cuenta, utiliza el X Help Desk.