---
title: "Gestion des erreurs"
description: "Récupérez-vous des erreurs HTTP TwexAPI, des échecs d'outils MCP, des limites de crédits et des retries d'actions d'écriture."
---

TwexAPI renvoie des erreurs à deux niveaux : **erreurs JSON-RPC MCP** (authentification avant l'exécution d'un outil) et **erreurs HTTP REST** (après qu'une requête atteint l'API). Conservez les codes de statut, les corps de réponse, les curseurs et les ID pour que les retries et la revue humaine restent sûrs.

## Enveloppe de réponse REST

Les appels réussis renvoient :

```json
{
  "code": 200,
  "msg": "success",
  "data": {}
}
```

Lorsque le statut HTTP n'est pas `2xx`, traitez la réponse comme un échec même si le corps inclut un champ `code`. Journalisez le corps complet, le chemin de requête et tout curseur déjà consommé.

## Récupération par statut HTTP

| Statut | Signification | Action |
| --- | --- | --- |
| `400` | Requête invalide, champ manquant ou corps mal formé | Corrigez l'entrée. **Ne pas** réessayer sans modification. |
| `401` | Clé API manquante ou invalide | Remplacez l'identifiant depuis le [tableau de bord](https://twexapi.io/dashboard). Vérifiez le formatage `Authorization: Bearer`. |
| `403` | Crédits épuisés, compte restreint ou action non autorisée | Consultez [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get). Rechargez ou supprimez les étapes d'écriture jusqu'au retour de l'accès. |
| `404` | Tweet, utilisateur, liste ou ressource introuvable | Vérifiez les ID, noms d'écran et fraîcheur du curseur. |
| `422` | Validation échouée sur une entrée structurée | Corrigez les champs de schéma documentés sur la page d'endpoint. Ne pas réessayer sans modification. |
| `429` | Limite de débit dépassée | Ralentissez selon [Limites de débit](/guides/rate-limits). Conservez `next_cursor` et les lignes complétées. |
| `5xx` | Défaillance de service transitoire ou échec de récupération en amont | Réessayez avec backoff exponentiel et plafond strict. |

## Crédits et solde

Les lectures et écritures comptabilisées consomment des crédits de compte. Lorsqu'une tâche traite de nombreuses pages, vérifiez le solde avant et après de longues exécutions :

```bash
curl --request GET \
  --url 'https://api.twexapi.io/balance' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Si les réponses `403` mentionnent des crédits ou l'accès :

1. Arrêtez les tâches planifiées qui continuent de solliciter l'API.
2. Confirmez le solde dans le tableau de bord.
3. Reprenez depuis le dernier curseur enregistré après restauration des crédits.

## Retries sûrs pour la pagination

Pour la recherche, les abonnés, les timelines et l'historique DM :

- Stockez `next_cursor`, `has_next_page` et tout `task_id` en dehors de la conversation de l'agent.
- Après `429` ou `5xx`, réessayez le **même curseur**, pas la page suivante.
- Après `400`, `404` ou `422`, inspectez les ID et paramètres de requête avant de réessayer.

## Actions d'écriture

Les endpoints d'écriture (tweet, réponse, like, follow, envoi de DM) nécessitent :

- Une clé API TwexAPI valide
- Un cookie Twitter ou `auth_token` enregistré sur la requête

Règles de récupération :

| Situation | Action |
| --- | --- |
| `401` sur écriture | Corrigez la clé API et les identifiants cookie avant de réessayer. |
| `403` sur écriture | Confirmez les crédits et que le compte connecté a toujours la permission. |
| Succès ambigu | Consultez le tweet, le DM ou l'état d'engagement avec un endpoint de lecture avant de dupliquer l'action. |
| Workflows d'agents | Exigez une approbation humaine avant tout appel MCP `read_only: false`. |

Public docs focus on API-key reads.

## Erreurs MCP

### Échec d'authentification avant l'exécution de l'outil

Lorsque l'authentification MCP échoue, `explore` et `twexapi_request` ne s'exécutent pas :

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}
```

Corrigez `x-api-key` ou `Authorization: Bearer` sur le client MCP, puis relancez l'appel d'outil.

### Erreur API renvoyée via `twexapi_request`

Lorsque l'appel REST sous-jacent échoue, conservez le résultat de l'outil :

```json
{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}
```

Appliquez le même tableau de récupération HTTP ci-dessus. Ne demandez pas au modèle de deviner un nouveau chemin — appelez `explore` à nouveau si la route a pu changer.

## Erreurs SDK et CLI

Les SDK générés mappent les échecs HTTP vers des exceptions natives du langage. Interceptez les erreurs à la frontière de la tâche, journalisez le code de statut et le corps de réponse, et routez `429`/`5xx` vers des politiques de retry.

Exemple Python :

```python
import requests

try:
    response = requests.get(
        "https://api.twexapi.io/balance",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        timeout=30,
    )
    response.raise_for_status()
except requests.HTTPError as exc:
    status = exc.response.status_code
    body = exc.response.text
    if status == 429:
        # Back off, preserve cursor, retry later
        ...
    elif status in (400, 404, 422):
        # Fix input; do not retry unchanged
        ...
    raise
```

Consultez les modèles spécifiques à chaque langage sur chaque [page SDK](/sdks).

## Modèle de backoff de retry

Utilisez un backoff exponentiel plafonné pour `429` et `5xx` :

```python
retry_delays_seconds = [5, 15, 45, 120]

for delay in retry_delays_seconds:
    response = call_twexapi()
    if response.ok:
        break
    if response.status_code in (429, 500, 502, 503, 504):
        time.sleep(delay)
        continue
    break  # 4xx other than 429: stop and fix input
```

Associez le backoff à [Limites de débit](/guides/rate-limits) pour que les tâches planifiées ne redémarrent pas immédiatement à plein QPS après un `429`.

## Notes spécifiques aux frameworks

| Runtime | Conseil |
| --- | --- |
| [LangChain](/guides/langchain) | Validez les modèles de transfert ; arrêtez le graphe sur `401`. |
| [Prefect](/guides/prefect) | Utilisez des retries de tâches avec jitter ; stockez les curseurs dans l'état de la tâche. |
| [n8n / Zapier / Make](/guides/no-code-workflow-handoff) | Routez `401`/`403` vers des alertes ops ; retardez les replays `429`. |
| [Agents MCP](/mcp/agent-handoff) | Ne supprimez jamais `next_cursor` après un succès partiel. |

## Pages associées

- [Limites de débit](/guides/rate-limits)
- [Authentification](/authentication)
- [Vue d'ensemble de l'API](/api-reference/overview)
- [Outils MCP](/mcp/tools)