> For the complete documentation index, see [llms.txt](https://ouvretaferme.gitbook.io/ouvretaferme/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ouvretaferme.gitbook.io/ouvretaferme/authentification/errors.md).

# Erreurs

Toute erreur de l'API rend un tableau JSON, même quand il n'y a qu'une erreur :

```json
[
  {
    "type": "authentication_error",
    "code": "access_denied",
    "message": "The resource owner or authorization server denied the request. (Missing \"Authorization\" header)"
  }
]
```

`type` vaut `authentication_error` pour une clé ou un jeton refusé, `resource_error` pour un champ refusé, et `api_error` pour tout le reste. `code` est stable et se teste dans votre code, `message` est une explication en clair qui peut changer.

## Authentification (401)

| `code`          | Cause                                                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_denied` | En-tête `Authorization` absent ou mal formé, clé ou jeton invalide, expiré ou révoqué. Le message précise lequel.                                             |
| `invalid_token` | La clé ou le jeton est bien formé et signé, mais Ouvretaferme ne le retrouve plus, par exemple après la suppression de la clé. Il faut en obtenir un nouveau. |

## Accès refusé (403)

| `code`                  | Cause                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `scope_not_allowed`     | La clé ou le jeton ne porte pas le scope qu'exige la route.                             |
| `scope_not_open`        | La route écrit, et l'écriture n'est pas encore ouverte à cette structure.               |
| `subscription_required` | La structure n'a pas l'abonnement qui ouvre l'API.                                      |
| `structure_not_allowed` | L'API n'est pas ouverte à cette structure.                                              |
| `user_not_allowed`      | La personne qui a créé la clé ou autorisé l'application n'administre plus la structure. |

## Trop d'appels (429)

Les codes `rate_limit_second`, `rate_limit_minute`, `rate_limit_day` et `rate_limit_authentication`, accompagnés de l'en-tête `Retry-After`. Voir [Limites et journal des appels](/ouvretaferme/utilisation/limits.md).

## Que vérifier sur une erreur 401

* l'en-tête est bien au format `Authorization: Bearer <clé-ou-jeton>` ;
* la clé n'a pas été révoquée, ou le jeton OAuth2 n'a pas expiré (une heure) ;
* la clé a moins d'un an.

Les erreurs propres aux routes (`400` pour un champ ou un filtre refusé, `404`, `405`, `412`) sont décrites dans la [vue d'ensemble des routes](/ouvretaferme/endpoints/endpoints.md#erreurs).