Codes d’erreur
Décodez chaque erreur OneProvider : sens de chaque code de statut, message exact, délais, erreurs en cours de flux et cas où réessayer sans risque.
Ce que signifie chaque code de statut, le message exact que vous verrez et ce qu’il faut faire ensuite.
Tous les modèles, leurs capacités et leurs tarifs Index de la documentation pour les agents IA :https://oneprovider.dev/docs/llms.txt Forme des erreurs
Chaque erreur est un JSON de même forme sur tous les endpoints (/v1/messages, /v1/chat/completions, /v1/responses, /v1/models). L’erreur de solde contient aussi code :
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}Les SDK OpenAI lisent error.message dans ce corps comme d’habitude : vous voyez donc le même texte dans n’importe quel client.
Codes de statut
| Statut | error.type | Message et signification | Que faire |
|---|---|---|---|
| 400 | invalid_request_error | La requête est mal formée : JSON invalide, champ manquant ou valeur non autorisée. Le message désigne le problème. | Corrigez ce que le message indique et renvoyez la requête. Renvoyée telle quelle, elle produit la même erreur. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum L’entrée dépasse la fenêtre de contexte de ce modèle. N et M dépendent du modèle. | Raccourcissez l’historique ou les pièces jointes, ou choisissez un modèle avec un contexte plus grand. Claude Code compacte lui-même la conversation quand il voit cette erreur. |
| 400 | invalid_request_error | Model X is not available on this API key Le forfait de votre clé n’inclut pas ce modèle. | Choisissez un modèle listé par GET /v1/models ou sur la page des tarifs. |
| 401 | authentication_error | Invalid API key API key is required La clé est absente, mal saisie ou envoyée dans le mauvais en-tête. | Envoyez la clé sk-… telle quelle, sans guillemets ni espaces, dans x-api-key ou Authorization: Bearer. |
| 401 | authentication_error | API key is disabled La clé est désactivée ou le compte est inactif. | Vérifiez la clé dans votre espace client (page « Clés ») ou écrivez à @Oneproviderhelpbot. |
| 403 | permission_error | API key expired La clé a dépassé sa date d’expiration. | Renouvelez la clé ou créez-en une nouvelle dans votre espace client (page « Clés »). |
| 404 | not_found_error | The requested API endpoint does not exist Le plus souvent une base URL incorrecte, par exemple /v1/v1 dans le chemin. | Claude Code et les SDK Anthropic : https://api.oneprovider.dev. SDK OpenAI et clients compatibles OpenAI : https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit Le corps de la requête dépasse 32 Mo. | Envoyez des images et des fichiers plus petits ou moins nombreux, ou répartissez le travail en plusieurs requêtes. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev Le solde de l’espace client est épuisé ou la limite de dépense de la clé est atteinte. Le corps contient error.code insufficient_quota et la réponse porte l’en-tête x-should-retry: false. | Ne réessayez pas. Rechargez l’espace client (bot ou app.oneprovider.dev) ou relevez la limite de la clé, puis renvoyez la requête. |
| 429 | rate_limit_error | Rate limit exceeded; retry later Trop de requêtes en peu de temps. Peut inclure un en-tête Retry-After. | Attendez Retry-After secondes s’il est présent, sinon réessayez avec une pause croissante. Si cela se répète, envoyez moins de requêtes en parallèle. |
| 500, 502 | server_error | Service temporarily unavailable; retry later Panne temporaire de notre côté. | Réessayez avec une pause croissante. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later Temporaire. Ni votre clé ni votre requête ne sont en cause. | Réessayez avec une pause croissante ; cela se résout en général en une minute. |
| 504 | server_error | Service timed out; retry later La requête a dépassé une limite de temps (voir ci-dessous). | Réessayez. Pour les réponses longues, activez stream: true. |
Limites de temps
- Une requête sans streaming doit commencer à répondre en 6 minutes au plus.
- Toute requête, streaming compris, est plafonnée à 10 minutes.
- Pour les générations longues, utilisez
stream: true: un flux commence à répondre tout de suite. Si une réponse demande plus de 10 minutes, découpez la tâche.
Erreurs dans un flux
Une fois le flux démarré, le statut est déjà 200 : l’erreur arrive donc sous forme d’événement. L’API Messages envoie une trame event: error avec le même corps d’erreur ; l’API Responses envoie un événement response.failed avec la cause dans response.error.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}Traitez-la comme le code de statut correspondant. La réponse partielle est incomplète : si l’erreur permet un nouvel essai, renvoyez la requête entière.
Quand réessayer
- Corrigez d’abord, ne réessayez pas : 400, 401, 403, 404, 413 et 429 avec
insufficient_balance. La même requête échoue de la même façon tant que vous ne changez pas la requête, la clé ou le solde. - Réessayez avec une pause croissante : 429
rate_limit_error, 500, 502, 503, 504. Par exemple 1 s, 2 s, 4 s et ainsi de suite jusqu’à une minute, avec un peu de gigue aléatoire. SiRetry-Afterest présent, attendez au moins ce délai. - Respectez
x-should-retry: false. Les SDK officiels d’Anthropic et d’OpenAI le font déjà : ils ne réessaient donc pas l’erreur de solde. - Vérifiez ce qu’il reste avec
GET /v1/dashboard/balance, voir Utilisation et facturation .
Comment réagissent les clients courants
- Claude Code. Affiche le message dans la session. Après un 401, Claude Code 2.1.231 et les versions plus récentes suppriment la clé enregistrée : vérifiez la clé et la base URL (https://api.oneprovider.dev, sans /v1), puis redéfinissez la clé. Sur l’erreur de solde, il s’arrête aussitôt : rechargez et continuez. Sur « prompt is too long », il compacte lui-même la conversation. Les erreurs temporaires 429 et 5xx sont réessayées automatiquement.
- Cursor. Affiche le texte de l’erreur dans le chat. Vérifiez la clé API et la base URL https://api.oneprovider.dev/v1 dans les réglages du modèle, rechargez si le message concerne le solde, puis renvoyez le message.
- Codex. Affiche l’erreur de solde sous la forme « Quota exceeded » et s’arrête : rechargez et relancez la commande. Il réessaie d’abord lui-même les erreurs temporaires.
- Cline. Affiche l’erreur dans la tâche avec un bouton Retry (Réessayer). Corrigez d’abord la clé, la base URL ou le solde, puis appuyez sur Retry.
- Continue. Affiche le texte de l’erreur dans le panneau de chat. Corrigez la cause et renvoyez le message.