> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/keryo-docs-fr/developpeurs/rate-limits-and-errors.md).

# Limites de débit & erreurs

Limitation de débit à la publication, erreurs de scope et d'offre, et bonnes pratiques de gestion des erreurs.

Cette page explique comment l'API Keryo signale les limites de débit et les erreurs, et comment votre intégration doit y réagir. Elle s'applique aussi bien aux clés API qu'aux jetons d'accès OAuth 2.1 du MCP.

## Limitation de débit

**La publication et la planification sont limitées en débit.** Si vous appelez `POST /posts/send/:id` ou `PUT /posts/schedule/:id` trop fréquemment, la requête est régulée.

* Temporisez et réessayez après un délai lorsque vous atteignez une limite de débit.
* Regroupez ou espacez les publications plutôt que d'enchaîner de nombreuses requêtes.
* Pour les publications échouées (et non les limites de débit), un endpoint dédié `POST /posts/retry/:id` permet de relancer.

{% hint style="warning" %}
La publication est **irréversible**. Vérifiez les comptes cibles et le contenu avant d'appeler l'endpoint de publication, et ne relancez pas aveuglément une publication qui a pu partiellement réussir — vérifiez d'abord le statut du post.
{% endhint %}

## Erreurs d'autorisation

Les jetons scopés (clés API et jetons d'accès OAuth 2.1) sont vérifiés à chaque requête, à la fois sur les **scopes** et sur l'**offre**.

| Statut             | Quand                                | Signification                                                                                                                                                                                                                          |
| ------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Jeton manquant ou invalide           | L'en-tête `Authorization` est absent, mal formé, expiré, ou le jeton est révoqué. Pour le serveur MCP, un défi `WWW-Authenticate` est renvoyé afin que le client puisse découvrir le serveur d'autorisation.                           |
| `403 Forbidden`    | Scope manquant ou offre insuffisante | Le jeton s'est authentifié correctement, mais il ne possède pas le **scope** requis par l'endpoint, ou l'**offre** du compte est trop basse pour l'action (par ex. import en dessous de Freelance, statistiques en dessous de Studio). |

{% hint style="info" %}
La distinction est importante pour la gestion des erreurs :

* `401` → corrigez l'authentification (envoyez un jeton valide ; relancez le flux OAuth pour le MCP).
* `403` → corrigez l'autorisation (accordez le scope manquant, ou passez à une offre supérieure). Réessayer la même requête ne changera rien.
  {% endhint %}

### Exemples

Scope manquant sur un jeton scopé :

```http
POST /posts/send/post_123
Authorization: Bearer <cle-sans-posts:publish>

HTTP/1.1 403 Forbidden
```

Statistiques demandées sur une offre inférieure à Studio :

```http
GET /statistics/linkedin
Authorization: Bearer <cle-avec-stats:read-mais-offre-Freelance>

HTTP/1.1 403 Forbidden
```

> *Les corps de réponse d'erreur sont donnés à titre indicatif ; appuyez-vous sur le code de statut HTTP pour le contrôle de flux.*

## Gestion générale des erreurs

Suivez la sémantique standard des statuts HTTP :

* **2xx** — succès.
* **4xx** — un problème avec la requête (authentification, autorisation, validation ou ressource introuvable). Corrigez la requête avant de réessayer ; relancer une requête `4xx` inchangée ne réussira généralement pas.
* **429** — vous êtes limité en débit (voir plus haut). Temporisez et réessayez plus tard.
* **5xx** — un problème côté serveur. Réessayez avec une temporisation ; si cela persiste, contactez le support.

Bonnes pratiques d'intégration recommandées :

1. **Lisez d'abord le code de statut**, puis le corps pour le détail.
2. **Distinguez `401` de `403`** — l'un est un problème d'authentification, l'autre de permissions / d'offre.
3. **Temporisez sur les limites de débit et les 5xx**, avec des délais exponentiels.
4. **Ne relancez jamais une publication automatiquement** sans vérifier le statut actuel du post, la publication étant irréversible.

## Pages associées

* [Authentification](/keryo-docs/keryo-docs-fr/developpeurs/authentication.md) — scopes et gating par offre.
* [Référence de l'API](/keryo-docs/keryo-docs-fr/developpeurs/api-reference.md) — les endpoints et leurs scopes requis.
* [Connecteur MCP](/keryo-docs/keryo-docs-fr/developpeurs/mcp-connector.md) — le flux `401` / `WWW-Authenticate` d'OAuth 2.1.