Limites & codes d’erreur

L’API PetitPanda applique des rate limits par clé et retourne des codes HTTP standards avec un payload d’erreur structuré. Ce guide te donne tout ce qu’il faut pour gérer ça proprement côté client.

Rate limits par plan

Plan	Par minute	Par heure
Pro	100 req/min	1 000 req/h
Business	200 req/min	5 000 req/h
Enterprise	illimité	illimité

Les limites s’appliquent par clé API, pas par compte. Si tu as 3 clés actives sur un plan Pro, chaque clé a son propre quota de 100 req/min.

Headers de quota

Toutes les réponses incluent des headers pour suivre ton quota en temps réel :

Header	Description
`X-RateLimit-Limit`	Quota par minute du plan
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre courante
`X-RateLimit-Reset`	Timestamp UNIX du reset de la fenêtre

Exemple de réponse :


HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1747749900
Content-Type: application/json

💡 Surveille X-RateLimit-Remaining dans ton code et mets en pause tes appels avant d’atteindre 0. C’est plus propre que d’attraper les 429 après coup.

Codes d’erreur HTTP

Code	Signification	Cause typique
`400`	Bad Request	JSON mal formé, champ requis manquant
`401`	Unauthorized	Clé API absente, invalide, ou révoquée
`402`	Payment Required	Crédits insuffisants pour l’opération
`403`	Forbidden	Scope manquant sur la clé (ex : appel `/generate-post` sans `reels:generate`)
`404`	Not Found	Ressource inexistante (`draft_id`, `schedule_id` introuvable)
`422`	Unprocessable Entity	Valeur invalide (ex : `platform: "facebook"` qui n’est pas supporté)
`429`	Too Many Requests	Rate limit dépassé. Attends le `X-RateLimit-Reset`
`500`	Internal Server Error	Bug côté PetitPanda. Réessaie avec backoff, puis contacte le support

Format des erreurs

Toutes les erreurs retournent un body JSON avec la même structure :


{
  "error": {
    "code": "insufficient_credits",
    "message": "Tu n'as pas assez de crédits pour cette opération.",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}

Champ	Type	Description
`error.code`	string	Code machine-readable, stable d’une version à l’autre
`error.message`	string	Message lisible en français
`error.details`	object \| null	Infos contextuelles (variables selon l’erreur)

Codes d’erreur courants

Code	Description
`invalid_api_key`	Clé absente, mal formée, ou révoquée
`missing_scope`	La clé n’a pas le scope requis par cet endpoint
`insufficient_credits`	Pas assez de crédits pour cette opération
`invalid_platform`	Valeur de `platform` non reconnue
`draft_not_found`	`draft_id` inconnu ou n’appartenant pas à ton compte
`schedule_conflict`	Une publication est déjà programmée à cette heure pour cette plateforme
`rate_limit_exceeded`	Quota par minute ou par heure dépassé
`platform_token_expired`	Le token OAuth de la plateforme cible doit être renouvelé

Bonnes pratiques

Retry exponentiel sur 429 et 500. Attends 1s, puis 2s, puis 4s, max 5 tentatives.
Pas de retry sur 4xx (sauf 429). Une 400 ou 422 ne deviendra jamais valide avec un retry. Corrige le payload.
Log error.code, pas error.message. Le code est stable, le message peut changer.
Surveille credits.low via webhook plutôt que de checker credits_remaining à chaque appel.

Et après ?

Comprendre les scopes et l’auth : Authentification & clés API
Suivre ta conso de crédits : Crédits