Codes de réponse et erreurs

L’API X fournit les codes de réponse et d’erreur suivants pour aider à comprendre et à diagnostiquer les problèmes en temps réel. Utilisez le guide de débogage et l’index des erreurs ci-dessous pour des informations supplémentaires.

Les réponses réussies sont indiquées par un code HTTP de la série 200 et une charge utile au format JSON contenant le ou les objets demandés, créés, modifiés ou supprimés, ainsi qu’une indication de la manière dont le serveur a interprété votre requête.

Les réponses d’erreur sont renvoyées avec un code HTTP hors série 200. Des codes d’erreur différents correspondent à des causes d’erreur différentes. L’API X s’efforce de renvoyer des codes d’état HTTP appropriés pour chaque requête.

​

Codes d’état HTTP de X API v2

Code	Texte	Description	Conseils de dépannage
200	OK	La requête a abouti.
400	Bad Request	La requête est invalide ou ne peut pas être traitée. Un message d’erreur complémentaire apportera des précisions. Les requêtes sans authentification ou avec des paramètres de query invalides sont considérées comme invalides et renverront cette réponse.	Vérifiez le format de votre query JSON. Par exemple, si votre règle contient des guillemets doubles associés à une correspondance exacte ou à un autre opérateur, vous devrez peut‑être les échapper à l’aide d’une barre oblique inverse pour les distinguer de la structure du format JSON.
401	Unauthorized	Un problème est survenu lors de l’authentification de votre requête. Cela peut être dû à des informations d’authentification manquantes ou incorrectes. Ce code peut également être renvoyé dans d’autres circonstances non définies.	Vérifiez que vous utilisez la bonne méthode d’authentification et que vos identifiants sont corrects.
403	Forbidden	La requête est comprise, mais elle a été refusée ou l’accès n’est pas autorisé. Un message d’erreur complémentaire expliquera pourquoi.	Vérifiez que votre compte développeur inclut l’accès à l’endpoint que vous essayez d’utiliser. Vous devrez peut‑être aussi faire inscrire votre App sur liste d’autorisation (p. ex., Engagement API ou X Ads API) ou demander l’accès.
404	Not Found	L’URI demandée est invalide ou la ressource demandée, telle qu’un utilisateur, n’existe pas.	Vérifiez que vous utilisez des paramètres valides et l’URI correcte pour l’endpoint que vous utilisez.
409	Connection Exception	Renvoyé lors d’une tentative de connexion à un flux filtré qui n’a aucune règle.	Vérifiez que vous avez créé au moins une règle sur le stream auquel vous vous connectez. Le flux filtré ne renverra que les Posts correspondant à une règle active. S’il n’y a aucune règle, le stream ne renverra aucun Post.
429	Too Many Requests	Renvoyé lorsqu’une requête ne peut pas être traitée parce que la limite de taux de l’App ou le Post cap est épuisé. Voir Rate Limiting.	Vérifiez le nombre de requêtes autorisées par fenêtre temporelle pour l’endpoint que vous utilisez. Attendez la réinitialisation de la fenêtre. Espacez vos requêtes pour éviter d’atteindre les limites de taux ou passez au forfait de données supérieur.
500	Internal Server Error	Un dysfonctionnement est survenu. Il s’agit généralement d’une erreur temporaire, par exemple en cas de forte charge ou si un endpoint rencontre temporairement des problèmes.	Consultez la page d’état de X API ou le forum de la communauté des développeurs pour voir si d’autres rencontrent des problèmes similaires, ou attendez et réessayez plus tard.
501	Unimplemented	X API ne prend pas en charge cet endpoint et ne peut pas exécuter la requête.
503	Service Unavailable	Les serveurs X sont opérationnels, mais surchargés de requêtes. Réessayez plus tard.	Consultez la page d’état de X API ou le forum de la communauté des développeurs pour voir si d’autres rencontrent des problèmes similaires, ou attendez et réessayez plus tard.

Lorsqu’une erreur survient pendant une requête, des informations détaillées sur l’erreur sont renvoyées dans le corps de la réponse pour aider à diagnostiquer le problème. Un champ type, qui est une URI, indique la nature du problème, tandis que des champs supplémentaires fournissent des précisions. Les champs type, title et detail sont toujours renvoyés dans ces corps (voir le tableau ci‑dessous). Tous les champs supplémentaires, comme dans l’exemple ci‑dessous, varieront en fonction du type d’erreur.

{
  "client_id": "101010101",
  "required_enrollment": "Standard Basic",
  "registration_url": "https://developer.twitter.com/en/account",
  "title": "Client interdit",
  "detail": "Cette requête doit être effectuée à l’aide d’un compte développeur approuvé et inscrit à l’endpoint demandé. Pour en savoir plus, consultez notre documentation.",
  "reason": "client-not-enrolled",
  "type": "https://api.x.com/2/problems/client-forbidden"
}

​

Erreurs partielles

Dans certains cas, vous pouvez voir les erreurs détaillées ci‑dessus dans une réponse qui a renvoyé un code d’état 200. Dans ces cas, l’endpoint est conçu pour renvoyer les data qu’il peut, tout en fournissant des erreurs détaillées concernant ce qu’il n’a pas pu renvoyer.

Par exemple, l’endpoint de recherche de Posts permet à une App développeur X de demander plusieurs id. Si certains de ces Posts sont disponibles mais que l’un d’eux a été supprimé, les Posts disponibles seront renvoyés dans le champ data de la réponse. Un champ errors supplémentaire sera renvoyé dans la charge utile, indiquant quel(s) Post(s) demandé(s) n’ont pas pu être renvoyé(s). Le même format que pour les erreurs de requête complètes est utilisé afin de faciliter le diagnostic des problèmes.

​

Informations sur les erreurs

Chaque type de problème indique la nature du problème rencontré. Une liste complète des problèmes que vous pouvez rencontrer figure également dans notre spécification API.

L’X API tente de renvoyer des codes d’état HTTP appropriés pour chaque requête.

Titre	Type	Description
Problème générique	about:blank	Un problème générique sans information supplémentaire au-delà de celle fournie par le code d’état HTTP.
Problème de requête invalide	https://api.X.com/2/problems/invalid-request	Un problème indiquant que cette requête est invalide. Si votre requête inclut un corps POST, assurez-vous que le contenu est un JSON valide et qu’il correspond à la spécification OpenAPI.
Problème de ressource introuvable	https://api.X.com/2/problems/resource-not-found	Un problème indiquant qu’un Post, un utilisateur, etc. donné n’existe pas.
Problème de ressource non autorisée	https://api.X.com/2/problems/not-authorized-for-resource	Un problème indiquant que vous n’êtes pas autorisé à voir un Post, un utilisateur, etc. particulier.
Problème client interdit	https://api.X.com/2/problems/client-forbidden	Un problème indiquant que votre client n’est pas autorisé à effectuer cette requête.
Problème de ressource non permise	https://api.X.com/2/problems/disallowed-resource	Un problème indiquant que la ressource demandée contrevient aux principes de cette API.
Problème d’authentification non prise en charge	https://api.X.com/2/problems/unsupported-authentication	Un problème indiquant que l’authentification utilisée n’est pas prise en charge.
Problème de plafond d’utilisation	https://api.X.com/2/problems/usage-capped	Un problème indiquant qu’un plafond d’utilisation a été dépassé.
Problème de connexion	https://api.X.com/2/problems/streaming-connection	Un problème indiquant un dysfonctionnement de la connexion.
Problème de client déconnecté	https://api.X.com/2/problems/client-disconnected	Votre client s’est déconnecté.
Problème de déconnexion opérationnelle	https://api.X.com/2/problems/operational-disconnect	Vous avez été déconnecté pour des raisons opérationnelles.
Problème de limite de règles	https://api.X.com/2/problems/rule-cap	Vous avez dépassé le nombre maximal de règles.
Problème de longueur de règle	https://api.X.com/2/problems/rule-length	Vous avez dépassé le nombre maximal de caractères autorisés dans votre query ou votre règle, selon votre niveau d’accès. Voir niveaux d’accès.
Problème de règles invalides	https://api.X.com/2/problems/invalid-rules	La règle que vous avez soumise est invalide.
Problème de règles en double	https://api.X.com/2/problems/duplicate-rules	La règle que vous avez soumise est un doublon.

​

Conseils de dépannage

Débogage de votre code

Lors du développement d’une application, il est normal de rencontrer ponctuellement des erreurs ou des comportements inattendus. Voici quelques conseils pour déboguer votre code :

Commencez par décomposer le problème en éléments plus simples afin d’identifier précisément où il se situe. Par exemple, si vous intégrez un endpoint REST ou de streaming, la cause peut relever de l’un des points suivants :

• L’endpoint nécessite une authentification adéquate.
• L’endpoint requiert des paramètres et des en‑têtes valides. Toute règle de filtrage doit être construite avec les bons opérateurs et la syntaxe appropriée.
• L’URI de l’endpoint doit être correcte et, pour les endpoints REST, la méthode HTTP appropriée doit être utilisée.
• Les données ou la ressource auxquelles vous tentez d’accéder ne vous sont pas accessibles (par exemple, les données privées ne sont disponibles que pour les utilisateurs authentifiés).
• Votre offre de données actuelle vous donne accès uniquement à certains endpoints et à des limites de taux spécifiques. Consultez votre developer portal pour en savoir plus.
• Votre code utilise une bibliothèque tierce pour intégrer l’endpoint.
• Votre code doit analyser correctement la réponse de l’endpoint.

Lisez le message d’erreur associé : il devrait vous donner une bonne indication de la nature du problème. Utilisez les tableaux de la section Codes d’erreur et de réponse pour des conseils de dépannage spécifiques à chaque code.

Pour les endpoints REST, vous pouvez utiliser un client REST comme Postman ou Insomnia pour valider les étapes (1) à (5) ci‑dessus (consultez notre guide « Premiers pas avec Postman »). Si la requête exécutée avec le client REST renvoie un code d’état 200 (succès), vous pouvez supposer que le problème provient de votre code ou de la bibliothèque que vous utilisez, et non de la requête à l’endpoint elle‑même.

Pour les endpoints de streaming, vous pouvez utiliser cURL (un outil en ligne de commande pour récupérer ou envoyer des requêtes en utilisant la syntaxe d’URL) afin de déterminer si le problème provient de la requête vers l’endpoint (étapes (1) à (5) ci‑dessus) ou de votre code lui‑même (étapes (6) à (7) ci‑dessus).

Problèmes d’authentification

• Vérifiez que vous utilisez la méthode d’authentification adéquate requise par l’endpoint. Vous pouvez l’identifier via la page de référence de l’API de cet endpoint.
• Vérifiez que vos informations d’authentification sont correctes. Vous pouvez vérifier ou régénérer les clés et jetons de votre App dans la section Apps de votre tableau de bord développeur (sous « Details »).
• Vérifiez que vous avez correctement autorisé votre requête OAuth 1.0a avec oauth_nonce, oauth_signature et oauth_timestamp.
• Si le problème persiste, envisagez d’utiliser une bibliothèque OAuth, un client REST comme Postman ou Insomnia, ou xurl.

Consultez notre guide sur l’authentification pour plus d’informations sur l’ensemble des points ci‑dessus.

Problèmes de limites de taux et de Post cap

Une erreur 429 peut survenir si vous atteignez une limite de taux pour un endpoint donné, ou si vous atteignez un Post cap.

Si l’erreur spécifique « Too many requests » est renvoyée, vous avez atteint la limite de taux de l’endpoint. En d’autres termes, vous avez dépassé le nombre maximal de requêtes autorisées pour un endpoint sur une période de temps donnée.

Notez que les limites de taux sont définies au niveau de l’App et de l’utilisateur.

• Niveau X App indique le nombre de requêtes autorisées lors de l’utilisation d’OAuth 2.0 App-Only, où les limites de taux sont déterminées globalement pour l’ensemble de l’App. Par exemple, si une méthode autorise 15 requêtes par fenêtre de limite de taux, elle vous permet d’effectuer 15 requêtes par fenêtre pour le compte de votre X App. Cette limite est totalement indépendante de la limite au niveau utilisateur. En savoir plus dans notre guide sur OAuth 2.0 App-Only.
• Niveau contexte utilisateur indique le nombre de requêtes pouvant être effectuées par access token utilisateur lors de l’utilisation du Contexte utilisateur OAuth 1.0a ou d’OAuth 2.0 Autorisation par code avec PKCE. Par exemple, si une méthode autorise 15 requêtes par fenêtre de limite de taux, elle autorise 15 requêtes par fenêtre et par access token utilisateur. En savoir plus dans notre guide sur la façon d’obtenir les Access Tokens d’un utilisateur avec OAuth 1.0a et OAuth 2.0.

Commencez par vérifier les limites de taux pour l’endpoint que vous utilisez. Vous trouverez ces informations sur la page de référence de l’API de l’endpoint et dans le nouveau tableau de bord du developer portal.

Consultez notre documentation pour plus d’informations sur les limites de taux, notamment comment utiliser les en-têtes HTTP pour suivre la position de votre App pour une limite de taux donnée, comment se remettre d’un code d’erreur 429 lié à une limite de taux, et des conseils pour éviter d’être limité dès le départ :

• Limites de taux pour les endpoints v2

Si vous avez reçu l’erreur spécifique « Usage cap exceeded: Monthly product cap », cela signifie que vous avez atteint le Post cap pour votre niveau d’accès. Nous fournissons de nombreux détails sur ces Post caps sur notre page de documentation.

Problèmes de Posts manquants

Suivez les étapes ci-dessous si vous vous attendiez à ce qu’un Post soit renvoyé, mais qu’il n’a pas été livré par l’endpoint.

• Vérifiez votre règle pour vous assurer que vous utilisez les opérateurs et la syntaxe corrects. Scindez la règle en clauses plus petites pour confirmer que vous utilisez la bonne syntaxe.
• Si le compte depuis lequel le Post a été envoyé était protégé au moment de la création du Post, le Post ne sera pas renvoyé — même si le compte est public au moment de la requête à l’endpoint. Vous pouvez généralement le vérifier avec X Advanced Search : si un Post n’apparaît pas via la fonctionnalité X Advanced Search, vous devez supposer qu’il ne sera pas renvoyé par l’endpoint.

Les étapes suivantes s’appliquent uniquement aux endpoints de streaming :

• Étiez-vous connecté au stream lorsque le Post a été envoyé ? Rappelez-vous que l’horodatage fourni dans l’Objet Post indique l’heure en UTC. Si vous avez subi une déconnexion au moment de l’envoi du Post, consultez les fonctionnalités de récupération et de redondance disponibles pour reconstituer toute data manquée.
• Votre règle était-elle en place lorsque le Post a été envoyé ? Rappelez-vous que l’horodatage fourni dans l’Objet Post indique l’heure en UTC.

Problèmes de déconnexion pour tampon plein

Vous pouvez rencontrer l’une des erreurs suivantes lorsque votre stream ne suit pas la cadence de livraison et que votre App ne consomme pas les data du stream assez rapidement :

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

This stream has been disconnected for operational reasons.

Nous autorisons un retard de livraison pendant une certaine période et disposons, de notre côté, d’un tampon de mise en attente temporaire pour chaque stream ; mais si vous ne rattrapez pas le retard, nous procédons à une déconnexion afin de vous permettre de vous reconnecter au point courant. Veuillez noter que cela peut entraîner une perte de data (pour les data présentes dans le tampon au moment de la déconnexion pour tampon plein).

Ces situations peuvent se produire lors de fortes pointes de data. De manière générale, nous recommandons d’utiliser un processus de mise en tampon distinct du processus de traitement afin de consommer rapidement les data.

Si vous êtes un client Enterprise utilisant des endpoints v1.1, vous pouvez en savoir plus sur l’optimisation de votre App pour éviter ce type de déconnexions dans nos articles sur la connexion et sur la consommation de data en streaming ici et ici.

Il existe une gamme d’outils pour récupérer les Posts manqués en raison d’une déconnexion, notamment ceux listés ci-dessous. Notez que les outils suivants ne sont disponibles qu’avec des endpoints v1.1 au niveau d’accès Enterprise.

• Redundant Connections - Avec plusieurs connexions, consommez le stream depuis plusieurs serveurs pour éviter les pertes de data lorsqu’une connexion est interrompue.
• Replay - Récupérez les data des 5 derniers jours via un stream séparé.
• Backfill - Reconnectez-vous dans les 5 minutes et reprenez là où vous vous étiez arrêté.
• Historical PowerTrack - Récupérez les data de l’intégralité des archives de X.

​

Obtenir de l’aide

Le forum de la communauté X est à votre disposition pour poser des questions techniques sur la plateforme développeur X. Il s’agit d’un forum de discussion où vous trouverez des questions d’autres développeurs ainsi que des informations techniques sur divers sujets liés à l’utilisation de l’X API.

Nous vous encourageons à participer aux échanges en répondant aux questions et en intervenant sur notre forum. Des employés de X y sont également présents pour fournir une assistance.

Forum de la communauté X

​

Avant de publier une question

• Recherchez dans la documentation développeur de X des informations liées à votre problème
• Recherchez sur le forum communautaire des questions similaires posées par d’autres développeurs
• Consultez les règles du forum communautaire

​

Lorsque vous publiez une question, veillez à inclure les informations suivantes

• Une description du problème
• L’appel à l’API effectué (incluez les en‑têtes, si possible)
• La réponse de X renvoyée (incluez tout message d’erreur)
• Ce que vous vous attendiez à recevoir à la place
• La liste des étapes suivies pour diagnostiquer le problème
• La liste des étapes nécessaires pour reproduire le problème
• Le cas échéant, la période durant laquelle le problème s’est produit
• Le cas échéant, l’ID d’App, l’ID de Post, etc.
• Tout extrait de code pertinent ou des captures d’écran

Veuillez n’inclure qu’un seul sujet/question par Post.

Si vous avez des demandes de fonctionnalités ou des commentaires, veuillez les soumettre via le X Developer Platform Feedback Form.

Pour les problèmes liés aux règles, tels que la suspension d’une App, veuillez contacter le Policy support.

Pour les problèmes liés à X, tels que la connexion et l’assistance relative au compte, veuillez utiliser le X Help Desk.