# Erreurs et limites de l'API

> La forme JSON de chaque erreur de l'API REST d'Endless, le champ data.code qui en donne la raison et les en-têtes RateLimit pour 1 000 requêtes par minute.

Source: https://endless.app/fr/docs/reference/api-errors

Chaque erreur de l'API REST d'Endless sur `https://api.endless.app` renvoie du JSON sous une seule forme, et chaque réponse indique combien de requêtes il vous reste. Le versionnage a [sa propre page](/reference/api-versioning).

## La forme d'une erreur

```json
{
  "code": "FORBIDDEN",
  "status": 403,
  "message": "Your role does not have permission to do this",
  "data": { "code": "permission_denied" }
}
```

| Champ                | Ce que c'est                                                                                          |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| `code`               | Le statut HTTP sous forme de mot : `BAD_REQUEST`, `UNAUTHORIZED`, `NOT_FOUND`, …                      |
| `status`             | Le statut HTTP sous forme de nombre                                                                   |
| `message`            | Une phrase destinée à une personne. Sa formulation peut changer, ne vous appuyez donc pas dessus      |
| `data.code`          | La raison lisible par une machine, en `snake_case`. **C'est le champ sur lequel baser votre logique** |
| `data.hint`          | Lorsqu'elle est présente, l'étape qui résout le problème                                              |
| `data.documentation` | Lorsqu'il est présent, un lien vers la référence de l'API                                             |

Le schéma `Error` du [document OpenAPI](https://api.endless.app/openapi.json) liste chaque `data.code`, et chaque opération de la [référence de l'API](/docs/api) liste ses statuts.

## Codes courants

| Statut | `data.code`                                      | Que faire                                                                 |
| ------ | ------------------------------------------------ | ------------------------------------------------------------------------- |
| 400    | (validation)                                     | `message` nomme le champ et la règle enfreinte                            |
| 400    | `unsupported_api_version`                        | Voir [Versionnage de l'API](/reference/api-versioning)                    |
| 401    | `missing_token`                                  | Envoyez `Authorization: Bearer <token>`                                   |
| 401    | `invalid_token`                                  | Le jeton n'a pas été validé ou a expiré. Obtenez-en un nouveau            |
| 402    | `insufficient_credits`, `exceeds_spending_limit` | L'espace de travail ou l'appelant ne peut pas payer cet appel             |
| 403    | `permission_denied`, `forbidden`                 | Le rôle ou l'accès de l'appelant ne l'autorise pas                        |
| 404    | `not_found`, `organization_not_found`, …         | La ressource n'existe pas, ou l'appelant ne peut pas l'ouvrir             |
| 404    | `route_not_found`                                | Aucune opération ne correspond au chemin (jamais une page HTML)           |
| 404    | `invalid_path_parameter`                         | Un identifiant du chemin ne peut désigner aucune ressource                |
| 429    | `rate_limited`                                   | Attendez le nombre de secondes indiqué dans `retry_after`, puis réessayez |

## Limites de requêtes

- **Limite :** 1 000 requêtes par période de 60 secondes et par appelant, dans une politique nommée `default`. Un seul compteur par appelant sur tous les serveurs.
- **Fenêtre fixe :** elle se réinitialise d'un coup, réglez donc votre rythme sur `RateLimit-Remaining`, pas sur un débit supposé régulier.
- **Les crédits sont à part :** un solde épuisé ou un plafond de dépenses atteint renvoie `402`, pas `429`.

Chaque réponse de l'API, réussie ou non, porte le compteur sous deux formes (les navigateurs peuvent aussi les lire) :

```http
RateLimit-Policy: "default";q=1000;w=60
RateLimit: "default";r=997;t=42
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 42
```

`r` / `RateLimit-Remaining` correspondent aux requêtes restantes ; `t` / `RateLimit-Reset` aux secondes avant la réinitialisation. Au-delà de la limite, l'API renvoie `429` avec un en-tête `Retry-After` et le même nombre de secondes dans le corps :

```json
{
  "code": "TOO_MANY_REQUESTS",
  "status": 429,
  "message": "Too many requests.",
  "data": {
    "code": "rate_limited",
    "hint": "Wait 42s, then retry. Every response carries RateLimit headers — read them to pace yourself before you are refused.",
    "documentation": "https://endless.app/docs/api"
  },
  "retry_after": 42
}
```

## Sources lisibles par une machine

- [Index de l'API](https://api.endless.app/) : ses objets `rate_limit` et `errors` décrivent cette politique.
- [Document OpenAPI](https://api.endless.app/openapi.json) : le schéma `Error` de chaque réponse d'erreur.
- Le [serveur MCP](/connect) a sa propre limite : 60 appels d'outils par minute et par compte.