Documentation API développeur Erreurs Erreurs Le format des erreurs de l’API, au format d’OpenAI, la liste complète des codes avec leur statut et la conduite à tenir, et leur lecture avec les SDK.
Les erreurs de l’API suivent le format de l’API d’OpenAI : les SDK d’OpenAI les lisent sans réglage. Chaque erreur a un statut HTTP, un type , un code stable à tester dans votre code, et un message en anglais destiné aux développeurs.
Exemple : solde insuffisant Copier {
"error" : {
"message" : "insufficient credits" ,
"type" : "insufficient_quota" ,
"code" : "insufficient_credits" ,
"param" : null ,
"required_credits" : 5200 ,
"balance_credits" : 310
}
} Champ Type Description message chaîne Explication lisible, en anglais. Ne la testez pas dans votre code : elle peut changer. type chaîne Famille de l’erreur (voir ci-dessous). code chaîne ou null Code précis et stable. null pour quelques erreurs sans code dédié (corps JSON illisible, paramètre mal formé). param chaîne ou null Le paramètre en cause, quand il y en a un (model , messages , input …). autres champs Certaines erreurs ajoutent des détails : required_credits , balance_credits , window , scope , held_credits , cap_credits , spent_credits .
Valeurs de type :
type Statuts Sens invalid_request_error 400, 404, 405, 409, 410, 411, 413, 422 La requête est à corriger. authentication_error 401, 403 Clé absente, refusée, ou utilisée hors de ses règles. permission_error 403 Les règles de votre organisation refusent la requête. insufficient_quota 402 Solde ou plafond de dépense. rate_limit_error 429 Trop de requêtes pour l’instant : réessayez. server_error 500, 502, 503, 504 Panne de notre côté ou du modèle : réessayez.
Quand une erreur porte un en-tête Retry-After , attendez ce nombre de secondes avant de réessayer. Une erreur renvoyée par le modèle de conversation porte aussi l’en-tête X-Moon-Request-Id de la requête.
import os
import openai
from openai import OpenAI
client = OpenAI (base_url = "https://api.realmoon.ai/v1" , api_key = os.environ[ "MOONAI_API_KEY" ])
try :
client . chat . completions . create (
model = "anthropic/claude-haiku-4.5" ,
messages = [{ "role" : "user" , "content" : "Bonjour" }],
)
except openai . APIStatusError as e :
print (e.status_code, e.type, e.code, e.param)
print (e.body) # l’objet "error", avec ses champs en plus
print (e.response.headers. get ( "retry-after" ))
if e . code == "insufficient_credits" :
print ( "Rechargez le workspace :" , e.body. get ( "required_credits" ), "crédits nécessaires" )
except openai . APIConnectionError :
print ( "Le serveur n’a pas pu être joint." ) import OpenAI from 'openai' ;
const client = new OpenAI ({ baseURL : 'https://api.realmoon.ai/v1' , apiKey : process . env . MOONAI_API_KEY });
try {
await client . chat . completions .create ({
model : 'anthropic/claude-haiku-4.5' ,
messages : [{ role : 'user' , content : 'Bonjour' }] ,
});
} catch (err) {
if (err instanceof OpenAI . APIError ) {
console .log ( err .status , err .type , err .code , err .param);
console .log ( err .error); // l’objet "error", avec ses champs en plus
if ( err .code === 'insufficient_credits' ) {
console .log ( 'Rechargez le workspace :' , err . error ?.required_credits , 'crédits nécessaires' );
}
} else {
throw err;
}
} curl -i https://api.realmoon.ai/v1/chat/completions \
-H "Authorization: Bearer sk-moon-mauvaise-cle" \
-H "Content-Type: application/json" \
-d '{"model": "anthropic/claude-haiku-4.5", "messages": [{"role": "user", "content": "Bonjour"}]}' Nouvelles tentatives des SDK
Les SDK d’OpenAI réessayent seuls les erreurs 408, 409, 429 et 5xx (deux fois par défaut) en suivant Retry-After . Chaque nouvelle tentative est une nouvelle requête, avec sa propre réserve et son propre coût : voir Limites .
Ces erreurs peuvent arriver sur tous les points d’accès.
HTTP code Signification Que faire 401 invalid_api_key Clé absente, inconnue, révoquée ou expirée, workspace supprimé, ou propriétaire du workspace suspendu. Vérifiez l’en-tête Authorization: Bearer sk-moon-... et l’état de la clé dans l’onglet « Clés API ». 403 ip_not_allowed L’adresse qui appelle n’est pas dans la liste d’IP autorisées de la clé. Ajoutez l’adresse à une nouvelle clé, ou appelez depuis un serveur autorisé. 403 missing_scope La clé n’a pas la portée inference . Créez une clé depuis le portail. 403 org_policy Les règles de votre organisation refusent l’API, ce modèle, ou un modèle hébergé hors de l’Union européenne (type: permission_error ). Choisissez un modèle permis, ou voyez avec l’administrateur de l’organisation. 404 null not found : l’API n’est pas ouverte pour ce workspace.Contactez le support. 429 rate_limit_exceeded Plus de 600 requêtes par minute avec cette clé, trop de requêtes refusées avec cette clé, ou trop d’échecs d’authentification depuis cette adresse. Attendez Retry-After . Voir Limites . 503 service_unavailable L’authentification est momentanément indisponible. Réessayez après Retry-After (5 secondes). 503 org_policy_unavailable Les règles de votre organisation sont momentanément illisibles. Réessayez dans un instant.
HTTP code Signification Que faire 400 null invalid JSON body , body must be a JSON object , base64 invalide, formulaire multipart illisible, ou valeur mal formée (param la nomme).Corrigez le corps de la requête. 400 missing_required_parameter Un paramètre obligatoire manque ; param le nomme. Ajoutez-le. 400 invalid_value , invalid_request Paramètre d’adresse au mauvais type (par exemple limit=abc ), ou requête mal formée. Corrigez la valeur. 400 unknown_parameter Paramètre inconnu d’un point d’accès de médias. Retirez-le. 400 unsupported_parameter Paramètre refusé par l’API ou par le modèle ; param le nomme quand c’est possible. Retirez-le ou changez sa valeur. 400 unsupported_value Valeur hors de ce que le modèle accepte (taille, durée, format…). Voir la page du point d’accès. 400 unsupported_content Contenu de message non accepté (type de partie inconnu, fichier par identifiant, vidéo…). Voir Messages . 400 n_not_supported n différent de 1.Envoyez une requête par réponse voulue. 400 string_above_max_length Texte plus long que la limite du point d’accès. Raccourcissez-le. 404 unknown_url Invalid URL (POST / v1/ ...) : ce point d’accès n’existe pas.Vérifiez le chemin ; la liste est dans la vue d’ensemble . 405 method_not_allowed Méthode HTTP non prévue sur ce chemin. Utilisez la méthode documentée. 411 length_required Envoi multipart sans en-tête Content-Length . Laissez votre client calculer la taille (pas d’envoi par morceaux). 413 request_too_large , file_too_large Corps ou fichier trop volumineux. Voir les tailles dans Limites .
HTTP code Signification Que faire 404 model_not_found Le modèle n’existe pas, n’est pas public, ou ne sert pas ce point d’accès. Lisez GET / v1/ models (avec ?type= pour un média). 400 ou 413 context_length_exceeded La requête est trop longue pour la fenêtre de contexte du modèle (param: "messages" ). Raccourcissez les messages ou baissez max_tokens . 400 ou 413 no_available_route Le modèle ne peut pas servir cette requête telle qu’elle est (outil, format ou taille non pris en charge). Changez de modèle ou simplifiez la requête. 400 ou 413 invalid_request Le modèle a refusé la requête, avec son explication. Corrigez la requête d’après le message. 400 invalid_request_error Un modèle de médias a refusé la requête sans autre précision. Changez les paramètres ou le modèle. 400 content_policy_violation Le système de sécurité du modèle a refusé le contenu demandé (images, vidéos). Reformulez la demande. 503 pricing_unavailable Le prix du modèle est momentanément inconnu : la requête est refusée plutôt que mal facturée. Réessayez un peu plus tard.
Les refus du modèle (400, 413, 429) sont relayés sans le nom de son fournisseur, ses liens ni ses identifiants internes.
HTTP code Signification Que faire 402 insufficient_credits Le solde ne couvre pas la réserve de la requête, ou il est négatif. required_credits et balance_credits donnent les montants. Rechargez le workspace, ou réduisez la réserve avec max_tokens . Voir Coûts . 402 spend_cap_exceeded Un plafond de dépense est atteint. scope vaut workspace ou key , window vaut hour , day ou month . Attendez que la fenêtre glisse, ou relevez le plafond. 402 hold_exceeds_cap La réserve de cette seule requête dépasse ce que le plafond laisse. Détails : required_credits , cap_credits , spent_credits , scope , window . Baissez max_tokens , ou relevez le plafond. 429 credits_held_in_progress Le solde ou le plafond suffirait, mais les requêtes en cours retiennent le reste (held_credits ). Réessayez après Retry-After (2 secondes) ; fixez max_tokens quand beaucoup de requêtes tournent en même temps. 503 billing_unavailable Le solde n’a pas pu être lu ou débité. Réessayez plus tard.
HTTP code Signification Que faire 429 rate_limit_exceeded Limite de débit de la clé, voir Clé et accès . Attendez Retry-After . 429 model_rate_limited Le modèle de conversation reçoit trop de requêtes en ce moment. Rien n’est facturé. Attendez Retry-After , ou changez de modèle. 429 too_many_concurrent Trop de requêtes de médias en cours pour ce workspace. Attendez qu’une requête finisse (Retry-After : 5 secondes, 30 pour les vidéos). 429 upstream_rate_limited Le modèle de médias est surchargé. Attendez Retry-After (10 secondes).
HTTP code Signification Que faire 413 moon_blur_payload_too_large Un texte dépasse 500 000 caractères, trop long pour être analysé (param: "messages" ). Rien n’est envoyé ni facturé. Découpez le texte, ou désactivez Moon Blur sur la clé. 503 moon_blur_unavailable La protection des données personnelles n’a pas pu s’appliquer : la requête n’est pas envoyée au modèle et rien n’est facturé. Réessayez après Retry-After (5 secondes).
Voir Confidentialité .
HTTP code Signification Que faire 502 (ou autre 5xx) upstream_error Le modèle a échoué, a renvoyé une réponse illisible, ou n’a pas pu être joint. Réessayez, ou changez de modèle. 503 upstream_unavailable ou null Le modèle ou le service de médias est momentanément injoignable. Réessayez plus tard. 504 upstream_timeout Le modèle n’a pas répondu à temps. Pour la conversation, la réserve est gardée (voir Règlement ). Réessayez avec une requête plus courte, ou en flux.
Une fois le flux commencé, le statut HTTP est déjà parti (200). Une coupure côté modèle arrive comme un dernier événement :
Dernier événement d’un flux interrompu Copier { "error" : { "message" : "upstream stream interrupted" , "type" : "server_error" , "code" : "upstream_error" }} Les SDK la lèvent comme une erreur pendant l’itération. Voir Flux .
code HTTP Points d’accès Page audio_too_long 400 Transcription Audio billing_unavailable 503 Tous ceux qui sont facturés Crédits et plafonds content_policy_violation 400 Images, vidéos Modèle context_length_exceeded 400, 413 Conversation Conversation credits_held_in_progress 429 Tous ceux qui sont facturés Crédits et plafonds encrypted_document 400 OCR OCR file_too_large 413 Images, vidéos, transcription, OCR Requête hold_exceeds_cap 402 Tous ceux qui sont facturés Crédits et plafonds insufficient_credits 402 Tous ceux qui sont facturés Crédits et plafonds invalid_api_key 401 Tous Clé et accès invalid_content_type 400 Transcription Audio invalid_document 400 OCR OCR invalid_image 400 Images, vidéos, OCR Images invalid_request 400, 413 Conversation Modèle invalid_request_error 400 Médias Modèle invalid_value 400 Tous Requête ip_not_allowed 403 Tous Clé et accès job_not_recorded 503 Vidéos Vidéos length_required 411 Envois multipart Requête method_not_allowed 405 Tous Requête missing_required_parameter 400 Tous Requête missing_scope 403 Tous Clé et accès model_not_found 404 Tous ceux qui prennent un model Modèle model_rate_limited 429 Conversation Trop de requêtes moon_blur_payload_too_large 413 Conversation, embeddings Moon Blur moon_blur_unavailable 503 Conversation, embeddings Moon Blur n_not_supported 400 Conversation Requête no_available_route 400, 413 Conversation Modèle ocr_busy 503 OCR OCR ocr_timeout 504 OCR OCR org_policy 403 Tous ceux qui prennent un model Clé et accès org_policy_unavailable 503 Tous ceux qui prennent un model , liste des modèles Clé et accès pricing_unavailable 503 Conversation Modèle rate_limit_exceeded 429 Tous Clé et accès request_too_large 413 Médias Requête service_unavailable 503 Tous Clé et accès spend_cap_exceeded 402 Tous ceux qui sont facturés Crédits et plafonds string_above_max_length 400 Images, vidéos, voix Requête too_many_concurrent 429 Médias Trop de requêtes too_many_images 400 Retouche d’images Images too_many_pages 400 OCR OCR unknown_parameter 400 Médias Requête unknown_url 404 Tous Requête unreadable_document 422 OCR OCR unsupported_content 400 Conversation Conversation unsupported_format 400 Transcription, OCR Requête unsupported_model 400 Retouche d’images Images unsupported_parameter 400 Tous Requête unsupported_value 400 Médias Requête upstream_error 502, autres 5xx Tous ceux qui appellent un modèle Modèle en panne et service upstream_rate_limited 429 Médias Trop de requêtes upstream_timeout 504 Tous ceux qui appellent un modèle Modèle en panne et service upstream_unavailable 503 Médias Modèle en panne et service url_not_supported 400 OCR OCR video_expired 410 Téléchargement de vidéo Vidéos video_not_found 404 Suivi et téléchargement de vidéo Vidéos video_not_ready 409 Téléchargement de vidéo Vidéos
Une vidéo en échec porte aussi un error.code dans son objet (generation_failed , content_policy_violation , timeout , not_found ) : voir L’objet vidéo .