DocumentationOuvrir Moon AI
Parcourir la documentation

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.

Sur cette page

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.

FormatLien vers la section Format

Exemple : solde insuffisant
{
  "error": {
    "message": "insufficient credits",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "param": null,
    "required_credits": 5200,
    "balance_credits": 310
  }
}
ChampTypeDescription
messagechaîneExplication lisible, en anglais. Ne la testez pas dans votre code : elle peut changer.
typechaîneFamille de l’erreur (voir ci-dessous).
codechaîne ou nullCode précis et stable. null pour quelques erreurs sans code dédié (corps JSON illisible, paramètre mal formé).
paramchaîne ou nullLe paramètre en cause, quand il y en a un (model, messages, input…).
autres champsCertaines erreurs ajoutent des détails : required_credits, balance_credits, window, scope, held_credits, cap_credits, spent_credits.

Valeurs de type :

typeStatutsSens
invalid_request_error400, 404, 405, 409, 410, 411, 413, 422La requête est à corriger.
authentication_error401, 403Clé absente, refusée, ou utilisée hors de ses règles.
permission_error403Les règles de votre organisation refusent la requête.
insufficient_quota402Solde ou plafond de dépense.
rate_limit_error429Trop de requêtes pour l’instant : réessayez.
server_error500, 502, 503, 504Panne 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.

Lire une erreur avec un SDKLien vers la section Lire une erreur avec un SDK

Python
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.")
JavaScript
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
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"}]}'

Clé et accèsLien vers la section Clé et accès

Ces erreurs peuvent arriver sur tous les points d’accès.

HTTPcodeSignificationQue faire
401invalid_api_keyClé 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 ».
403ip_not_allowedL’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é.
403missing_scopeLa clé n’a pas la portée inference.Créez une clé depuis le portail.
403org_policyLes 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.
404nullnot found : l’API n’est pas ouverte pour ce workspace.Contactez le support.
429rate_limit_exceededPlus 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.
503service_unavailableL’authentification est momentanément indisponible.Réessayez après Retry-After (5 secondes).
503org_policy_unavailableLes règles de votre organisation sont momentanément illisibles.Réessayez dans un instant.

RequêteLien vers la section Requête

HTTPcodeSignificationQue faire
400nullinvalid 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.
400missing_required_parameterUn paramètre obligatoire manque ; param le nomme.Ajoutez-le.
400invalid_value, invalid_requestParamètre d’adresse au mauvais type (par exemple limit=abc), ou requête mal formée.Corrigez la valeur.
400unknown_parameterParamètre inconnu d’un point d’accès de médias.Retirez-le.
400unsupported_parameterParamètre refusé par l’API ou par le modèle ; param le nomme quand c’est possible.Retirez-le ou changez sa valeur.
400unsupported_valueValeur hors de ce que le modèle accepte (taille, durée, format…).Voir la page du point d’accès.
400unsupported_contentContenu de message non accepté (type de partie inconnu, fichier par identifiant, vidéo…).Voir Messages.
400n_not_supportedn différent de 1.Envoyez une requête par réponse voulue.
400string_above_max_lengthTexte plus long que la limite du point d’accès.Raccourcissez-le.
404unknown_urlInvalid URL (POST /v1/...) : ce point d’accès n’existe pas.Vérifiez le chemin ; la liste est dans la vue d’ensemble.
405method_not_allowedMéthode HTTP non prévue sur ce chemin.Utilisez la méthode documentée.
411length_requiredEnvoi multipart sans en-tête Content-Length.Laissez votre client calculer la taille (pas d’envoi par morceaux).
413request_too_large, file_too_largeCorps ou fichier trop volumineux.Voir les tailles dans Limites.

ModèleLien vers la section Modèle

HTTPcodeSignificationQue faire
404model_not_foundLe 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 413context_length_exceededLa 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 413no_available_routeLe 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 413invalid_requestLe modèle a refusé la requête, avec son explication.Corrigez la requête d’après le message.
400invalid_request_errorUn modèle de médias a refusé la requête sans autre précision.Changez les paramètres ou le modèle.
400content_policy_violationLe système de sécurité du modèle a refusé le contenu demandé (images, vidéos).Reformulez la demande.
503pricing_unavailableLe 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.

Crédits et plafondsLien vers la section Crédits et plafonds

HTTPcodeSignificationQue faire
402insufficient_creditsLe 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.
402spend_cap_exceededUn 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.
402hold_exceeds_capLa 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.
429credits_held_in_progressLe 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.
503billing_unavailableLe solde n’a pas pu être lu ou débité.Réessayez plus tard.

Trop de requêtesLien vers la section Trop de requêtes

HTTPcodeSignificationQue faire
429rate_limit_exceededLimite de débit de la clé, voir Clé et accès.Attendez Retry-After.
429model_rate_limitedLe 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.
429too_many_concurrentTrop 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).
429upstream_rate_limitedLe modèle de médias est surchargé.Attendez Retry-After (10 secondes).

Moon BlurLien vers la section Moon Blur

HTTPcodeSignificationQue faire
413moon_blur_payload_too_largeUn 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é.
503moon_blur_unavailableLa 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é.

Modèle en panne et serviceLien vers la section Modèle en panne et service

HTTPcodeSignificationQue faire
502 (ou autre 5xx)upstream_errorLe modèle a échoué, a renvoyé une réponse illisible, ou n’a pas pu être joint.Réessayez, ou changez de modèle.
503upstream_unavailable ou nullLe modèle ou le service de médias est momentanément injoignable.Réessayez plus tard.
504upstream_timeoutLe 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.

Erreurs pendant un fluxLien vers la section Erreurs pendant un 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
{"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.

Index des codesLien vers la section Index des codes

codeHTTPPoints d’accèsPage
audio_too_long400TranscriptionAudio
billing_unavailable503Tous ceux qui sont facturésCrédits et plafonds
content_policy_violation400Images, vidéosModèle
context_length_exceeded400, 413ConversationConversation
credits_held_in_progress429Tous ceux qui sont facturésCrédits et plafonds
encrypted_document400OCROCR
file_too_large413Images, vidéos, transcription, OCRRequête
hold_exceeds_cap402Tous ceux qui sont facturésCrédits et plafonds
insufficient_credits402Tous ceux qui sont facturésCrédits et plafonds
invalid_api_key401TousClé et accès
invalid_content_type400TranscriptionAudio
invalid_document400OCROCR
invalid_image400Images, vidéos, OCRImages
invalid_request400, 413ConversationModèle
invalid_request_error400MédiasModèle
invalid_value400TousRequête
ip_not_allowed403TousClé et accès
job_not_recorded503VidéosVidéos
length_required411Envois multipartRequête
method_not_allowed405TousRequête
missing_required_parameter400TousRequête
missing_scope403TousClé et accès
model_not_found404Tous ceux qui prennent un modelModèle
model_rate_limited429ConversationTrop de requêtes
moon_blur_payload_too_large413Conversation, embeddingsMoon Blur
moon_blur_unavailable503Conversation, embeddingsMoon Blur
n_not_supported400ConversationRequête
no_available_route400, 413ConversationModèle
ocr_busy503OCROCR
ocr_timeout504OCROCR
org_policy403Tous ceux qui prennent un modelClé et accès
org_policy_unavailable503Tous ceux qui prennent un model, liste des modèlesClé et accès
pricing_unavailable503ConversationModèle
rate_limit_exceeded429TousClé et accès
request_too_large413MédiasRequête
service_unavailable503TousClé et accès
spend_cap_exceeded402Tous ceux qui sont facturésCrédits et plafonds
string_above_max_length400Images, vidéos, voixRequête
too_many_concurrent429MédiasTrop de requêtes
too_many_images400Retouche d’imagesImages
too_many_pages400OCROCR
unknown_parameter400MédiasRequête
unknown_url404TousRequête
unreadable_document422OCROCR
unsupported_content400ConversationConversation
unsupported_format400Transcription, OCRRequête
unsupported_model400Retouche d’imagesImages
unsupported_parameter400TousRequête
unsupported_value400MédiasRequête
upstream_error502, autres 5xxTous ceux qui appellent un modèleModèle en panne et service
upstream_rate_limited429MédiasTrop de requêtes
upstream_timeout504Tous ceux qui appellent un modèleModèle en panne et service
upstream_unavailable503MédiasModèle en panne et service
url_not_supported400OCROCR
video_expired410Téléchargement de vidéoVidéos
video_not_found404Suivi et téléchargement de vidéoVidéos
video_not_ready409Téléchargement de vidéoVidé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.

Moon AI

Moon AI en action

0:00

À découvrir

Captures de chat.realmoon.ai du 29 octobre 2026, avec des données fictives.

Moon AI

Vos préférences

Aucun suivi publicitaire.

Ce site ne dépose aucun cookie publicitaire ni cookie de mesure d’audience : notre serveur compte les visites sans cookie. Votre thème et la fermeture de l’information sur les cookies sont mémorisés sur cet appareil.

L’application Moon AI possède ses propres réglages de confidentialité.