Codes d’erreur

Toutes les erreurs sont renvoyées avec un code HTTP explicite et un corps JSON. Le format suit la surface appelée : OpenAI sur /v1, Anthropic sur /anthropic.

Tableau des codes#

HTTP	Code	Cause	Que faire
400	`invalid_request_error`	Corps JSON invalide, paramètre hors bornes, contexte trop long, contenu non supporté (image, document).	Lire `error.param` : il nomme le champ fautif. Corriger la requête.
401	`invalid_api_key`	Clé absente, mal formée, inconnue ou révoquée.	Vérifier l'en-tête `Authorization: Bearer zir_ai_…`. Recréer une clé si besoin.
402	`insufficient_balance`	Portefeuille vide, ou requête qui dépasserait le coût maximum par requête ou le budget mensuel fixés sur la clé.	Recharger sur Top up : le service reprend immédiatement, sans redémarrage. Si le solde est suffisant, ajuster les limites de la clé sur API keys ou baisser `max_tokens`.
403	`account_disabled`	Accès API suspendu (abus, demande de votre part), ou requête refusée par les limites de la clé (modèle ou point d'entrée non autorisés, clé suspendue, ou clé qui porte une liste d'adresses IP que nous ne savons pas appliquer pour le moment).	Lire `error.message` : il dit quelle limite de la clé s'applique, à ajuster sur API keys. Sinon, contacter le support depuis la plateforme.
404	`model_not_found`	Nom de modèle inconnu ou modèle désactivé.	Utiliser `mina-flash`, `mina-low` ou `mina-full` (GET /v1/models).
409	`invalid_request_error`	Requête incompatible avec l'état courant : `Idempotency-Key` déjà utilisée pour un autre lot, fichier indisponible pour l'opération demandée, ou refus des moteurs disponibles.	Lire `error.message` : il dit lequel de ces cas s'applique.
413	`invalid_request_error`	Taille ou quota dépassé : corps JSON, fichier téléversé, sorties de lot, ou requête trop volumineuse pour les moteurs disponibles (limites).	Lire `error.message` : il dit s'il s'agit de la taille d'une requête ou d'un quota de fichiers. Réduire la requête, ou supprimer des fichiers devenus inutiles.
422	`invalid_request_error`	Requête que les moteurs disponibles n'ont pas pu traiter.	Lire `error.message` et corriger la requête : ce refus n'est pas transitoire, inutile de la renvoyer à l'identique.
429	`rate_limit_exceeded`	RPM ou requêtes simultanées dépassés.	Attendre `Retry-After` puis réessayer (limites).
500	`api_error`	Erreur interne CloudZIR.	Réessayer. Si cela persiste, envoyer le `X-Request-Id` au support.
501	`not_implemented`	Fonction annoncée mais pas encore disponible : aucun moteur n'y est branché sur cette plateforme. Ce n'est pas une panne passagère.	Ne pas réessayer : la réponse ne porte jamais `Retry-After` et le résultat ne changera pas. Lire `error.message`, qui nomme la fonction.
503	`overloaded`	Capacité saturée ou aucun moteur disponible pour cette requête.	Réessayer après `Retry-After`. Jamais facturé.

Format des réponses d'erreur#

Surface OpenAI (`/v1`)#

{
  "error": {
    "message": "Solde insuffisant. Rechargez votre compte sur https://plateforme.cloudzir.com/topup.",
    "type": "insufficient_balance",
    "param": null,
    "code": "insufficient_balance"
  }
}

Surface Anthropic (`/anthropic`)#

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Le champ 'max_tokens' est requis."
  }
}

Les SDK officiels OpenAI et Anthropic reconnaissent ces formats et lèvent leurs exceptions habituelles (RateLimitError, AuthenticationError, etc.).

Erreurs en cours de streaming#

Si l'incident survient après le premier octet, le flux ne peut plus changer de code HTTP (déjà 200). L'erreur arrive alors comme un événement :

data: {"error":{"message":"Erreur interne.","type":"api_error","param":null,"code":"api_error"}}

data: [DONE]

event: error
data: {"type":"error","error":{"type":"api_error","message":"Erreur interne."}}

Traitez donc toujours le cas « un objet error arrive au milieu du flux ».

Traitement recommandé#

Famille	Réessayer ?	Stratégie
400, 404, 409, 413, 422	Non	Bug applicatif : corriger la requête, journaliser.
401, 403	Non	Problème de configuration ou de compte : alerter un humain.
402	Non	Alerter l'exploitant (solde) et basculer sur une file d'attente.
501	Non	Fonction pas encore disponible : la requête aura toujours le même résultat, ne pas la renvoyer.
429, 500, 503	Oui	Attente exponentielle + jitter, 3 à 5 tentatives.

from openai import OpenAI, APIStatusError, RateLimitError

client = OpenAI(api_key=cle, base_url="https://api.cloudzir.com/v1")

try:
    r = client.chat.completions.create(model="mina-low", messages=messages)
except RateLimitError:
    ...  # attendre puis réessayer
except APIStatusError as exc:
    if exc.status_code == 402:
        alerter("Solde CloudZIR épuisé")
    elif exc.status_code in (500, 503):
        ...  # réessayer
    else:
        raise  # 400, 404, 409, 413, 422 : bug applicatif

Obtenir de l'aide#

Pour toute erreur inexpliquée, envoyez depuis Help & Feedback : le X-Request-Id, l'horodatage UTC, le modèle et le code reçu. C'est ce qui permet de retrouver la trace exacte côté serveur.

Réponse API