Erreurs et limites de l'API de la plateforme

Les erreurs de l’API de la plateforme utilisent un format de corps différent de celui des endpoints de modèles : le statut HTTP porte le résultat, et le corps JSON contient toujours success et, en cas d’échec, un code lisible par machine.

Format de réponse

En cas de succès, HTTP 200 est retourné :

{
  "success": true,
  "message": "",
  "data": {}
}

En cas d’échec, le vrai code de statut HTTP est utilisé et le corps contient un code lisible par machine :

{
  "success": false,
  "message": "Invalid Management Key",
  "code": "invalid_token"
}

message est localisé et peut changer d’une version à l’autre. Utilisez le code de statut HTTP et code dans la logique de votre programme.

Codes d’erreur

HTTP	code	Scénario
400	invalid_request	Paramètres invalides : montant hors limites, nom manquant ou trop long à la création, status différent de 1 / 2, activation d’une Key encore expirée ou épuisée, date d’expiration invalide, pagination ou plage temporelle invalide, ou ; non encodé dans la query
401	invalid_token	En-tête Authorization manquant, clé mal formée, ou clé introuvable ou supprimée
401	token_expired	La clé de gestion a expiré
401	token_revoked	La clé de gestion a été révoquée (clés existantes uniquement ; les nouvelles clés ne peuvent être que supprimées)
403	user_disabled	Le compte du propriétaire de la clé de gestion est désactivé
403	insufficient_scope	La clé de gestion ne dispose pas de la permission requise par cet endpoint
404	not_found	La clé API n’existe pas ou ne vous appartient pas (sans distinction), ou le chemin n’existe pas sous /api/open/v1
405	method_not_allowed	Le chemin existe mais ne prend pas en charge cette méthode HTTP
429	rate_limited	Limite de débit par clé de gestion dépassée
500	internal_error	Erreur serveur ; les détails internes ne sont pas retournés

Les chemins inconnus sous /api/open/v1 retournent 404 et une méthode HTTP incorrecte retourne 405, avec le corps d’erreur unifié ci-dessus ; code permet de distinguer « réessayer avec une autre méthode » de « chemin ou paramètres incorrects ».

Limites de débit

Portée	Limite	S’applique à	Réponse en cas de dépassement
Par clé de gestion	120 requêtes/minute	Tous les endpoints de l’API de la plateforme	429, avec code à rate_limited
Par utilisateur	30 requêtes/minute (par défaut)	Logs du compte, Exporter les logs, Usage, Usage par modèle, Usage par Key	429 ; le corps de la réponse peut être vide
Par IP client	180 requêtes/180 secondes (par défaut)	Partagée par tous les endpoints /api	429
Par IP client	100 requêtes/20 minutes (par défaut)	Endpoints sensibles comme Révéler une API Key	429 ; le corps de la réponse peut être vide

Traitez la limitation de débit selon le code de statut HTTP. Lorsque vous recevez 429, ralentissez et réessayez plus tard.

Les endpoints de modèles utilisent un autre format d’erreur et des limites distinctes ; voir Erreurs courantes.