Codes de réponse et erreurs

Codes d’état HTTP et gestion des erreurs pour X API

L’API X utilise les codes d’état HTTP standards. Les requêtes réussies renvoient un code 2xx ; les erreurs renvoient un code 4xx ou 5xx avec des détails dans le corps de la réponse.

---

​

Codes d’état HTTP

​

Codes de succès

Code	Signification	Description
200	OK	Requête réussie
201	Créé	Ressource créée (requêtes POST)
204	Aucun contenu	Succès sans corps de réponse (requêtes DELETE)

​

Codes d’erreur client

Code	Signification	Causes courantes
400	Requête incorrecte	JSON non valide, requête mal formée, paramètres obligatoires manquants
401	Non autorisé	Identifiants d’authentification non valides ou manquants
403	Interdit	Authentification valide mais aucun droit pour cette ressource ou action
404	Introuvable	La ressource n’existe pas ou a été supprimée
409	Conflit	Le flux ne contient aucune règle (flux filtré uniquement)
429	Trop de requêtes	Limite de débit ou plafond d’utilisation dépassé

​

Codes d’erreur du serveur

Code	Signification	Que faire
500	Erreur interne du serveur	Patientez puis réessayez ; vérifiez la page d’état
502	Mauvaise passerelle	Patientez puis réessayez
503	Service indisponible	X est surchargé ; patientez puis réessayez
504	Temps d’attente de la passerelle écoulé	Patientez puis réessayez

---

​

Format de la réponse d’erreur

Les réponses d’erreur incluent des détails structurés :

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

Champ	Description
type	URI qui identifie le type d’erreur
title	Brève description de l’erreur
detail	Explication spécifique concernant cette erreur

Des champs supplémentaires peuvent être présents en fonction du type d’erreur.

---

​

Types d’erreur

Type	Description
about:blank	Erreur générique (voir le code d’état HTTP correspondant)
.../invalid-request	Requête mal formée ou paramètres invalides
.../resource-not-found	Publication, utilisateur ou autre ressource inexistante
.../not-authorized-for-resource	Aucun accès au contenu privé/protégé
.../client-forbidden	App non enregistrée ou ne disposant pas des droits d’accès requis
.../usage-capped	Plafond d’utilisation atteint
.../rate-limit-exceeded	Limite de débit dépassée
.../streaming-connection	Problème de connexion au flux
.../rule-cap	Nombre maximal de règles de flux filtré atteint
.../invalid-rules	Erreur de syntaxe dans les règles
.../duplicate-rules	La règle existe déjà

---

​

Erreurs partielles

Certaines requêtes peuvent réussir partiellement. Une réponse avec un statut 200 peut inclure à la fois data et 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"
    }
  ]
}

Cela se produit lorsque vous demandez plusieurs ressources et que certaines d’entre elles sont indisponibles.

---

​

Résolution des erreurs courantes

401 Unauthorized

Vérifiez votre authentification :

• Vérifiez que vous utilisez la bonne méthode d’authentification pour l’endpoint
• Assurez-vous que les identifiants n’ont pas été régénérés entre-temps
• Vérifiez le format de l’en-tête Authorization
• Pour OAuth 1.0a, vérifiez le calcul de la signature

Guide d’authentification →

403 Forbidden

Vérifiez vos droits d’accès :

• Vérifiez que votre application a accès à cet endpoint
• Certains endpoints nécessitent une inscription ou une approbation spécifique
• Les endpoints en contexte utilisateur nécessitent des scopes OAuth appropriés
• La ressource peut être privée ou protégée

429 Too Many Requests

Soumis à des limites de taux :

• Vérifiez l’en-tête x-rate-limit-reset pour savoir quand réessayer
• Mettez en œuvre un backoff exponentiel
• Envisagez de mettre en cache les réponses
• Répartissez les requêtes sur la fenêtre temporelle

Guide sur les limites de taux →

400 Bad Request

Corrigez votre requête :

• Validez la syntaxe JSON
• Vérifiez qu’aucun paramètre requis ne manque
• Vérifiez les types de paramètres (chaînes vs nombres)
• Échappez les caractères spéciaux dans les requêtes

Missing expected posts

Vérifiez ces éléments :

• Les publications des comptes protégés ne sont visibles qu’avec une autorisation
• Les publications supprimées renvoient un code 404
• Certaines publications sont restreintes dans certaines régions
• Vérifiez que la syntaxe de la requête de recherche est correcte

Stream disconnections

Gérez la reconnexion :

• Mettez en œuvre une reconnexion automatique avec backoff
• Utilisez les fonctionnalités de récupération pour les données manquées
• Vérifiez les déconnexions dues à un buffer plein (client ne consommant pas assez rapidement)
• Vérifiez qu’au moins une règle de flux existe

Guide sur le streaming →

---

​

En-têtes de limitation de débit

Chaque réponse comprend des informations de limitation de débit :

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

En-tête	Description
x-rate-limit-limit	Nombre maximal de requêtes dans la fenêtre actuelle
x-rate-limit-remaining	Nombre de requêtes restantes
x-rate-limit-reset	Horodatage Unix indiquant le moment où la fenêtre est réinitialisée

---

​

Bonnes pratiques

Vérifiez les codes d’état HTTP

Vérifiez toujours le statut HTTP avant d’analyser le corps de la réponse.

Gérez les erreurs partielles

Vérifiez le tableau errors même lorsque le code de réponse est 200.

Implémentez une logique de nouvelle tentative

Utilisez un backoff exponentiel pour les erreurs 429 et 5xx.

Consignez les détails de la requête

Incluez l’ID de requête et l’horodatage pour faciliter le débogage.

---

​

Obtenir de l’aide

Lorsque vous publiez des questions sur des erreurs, incluez :

• l’URL de l’endpoint d’API
• les en-têtes de la requête (en masquant les identifiants)
• la réponse d’erreur complète
• ce que vous attendiez comme résultat
• les étapes que vous avez déjà suivies

Developer Forum

Posez vos questions et recherchez des solutions.

API Status

Vérifiez s’il existe des problèmes connus.