# 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.

## Format

```json title="Exemple : solde insuffisant"
{
  "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.

## Lire une erreur avec un SDK

```python title="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 title="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;
  }
}
```

```bash title="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"}]}'
```

> [!NOTE]
> **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](https://realmoon.ai/documentation/api/limites/#nouvelles-tentatives).

## Clé et accès

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](https://realmoon.ai/documentation/api/limites/#debit). |
| 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. |

## Requête

| 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](https://realmoon.ai/documentation/api/chat/#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](https://realmoon.ai/documentation/api/). |
| 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](https://realmoon.ai/documentation/api/limites/#tailles). |

## Modèle

| 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.

## Crédits et plafonds

| 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](https://realmoon.ai/documentation/api/couts/#reserve). |
| 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. |

## Trop de requêtes

| HTTP | `code` | Signification | Que faire |
| --- | --- | --- | --- |
| 429 | `rate_limit_exceeded` | Limite de débit de la clé, voir [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle). | 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). |

## Moon Blur

| 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é](https://realmoon.ai/documentation/api/confidentialite/#moon-blur).

## Modèle en panne et service

| 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](https://realmoon.ai/documentation/api/couts/#reglement)). | Réessayez avec une requête plus courte, ou en flux. |

## 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 :

```json title="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](https://realmoon.ai/documentation/api/chat/#flux).

## Index des codes

| `code` | HTTP | Points d’accès | Page |
| --- | --- | --- | --- |
| `audio_too_long` | 400 | Transcription | [Audio](https://realmoon.ai/documentation/api/audio/#transcription) |
| `billing_unavailable` | 503 | Tous ceux qui sont facturés | [Crédits et plafonds](https://realmoon.ai/documentation/api/erreurs/#credits) |
| `content_policy_violation` | 400 | Images, vidéos | [Modèle](https://realmoon.ai/documentation/api/erreurs/#modele) |
| `context_length_exceeded` | 400, 413 | Conversation | [Conversation](https://realmoon.ai/documentation/api/chat/#erreurs) |
| `credits_held_in_progress` | 429 | Tous ceux qui sont facturés | [Crédits et plafonds](https://realmoon.ai/documentation/api/erreurs/#credits) |
| `encrypted_document` | 400 | OCR | [OCR](https://realmoon.ai/documentation/api/ocr/) |
| `file_too_large` | 413 | Images, vidéos, transcription, OCR | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `hold_exceeds_cap` | 402 | Tous ceux qui sont facturés | [Crédits et plafonds](https://realmoon.ai/documentation/api/erreurs/#credits) |
| `insufficient_credits` | 402 | Tous ceux qui sont facturés | [Crédits et plafonds](https://realmoon.ai/documentation/api/erreurs/#credits) |
| `invalid_api_key` | 401 | Tous | [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle) |
| `invalid_content_type` | 400 | Transcription | [Audio](https://realmoon.ai/documentation/api/audio/#transcription) |
| `invalid_document` | 400 | OCR | [OCR](https://realmoon.ai/documentation/api/ocr/) |
| `invalid_image` | 400 | Images, vidéos, OCR | [Images](https://realmoon.ai/documentation/api/images/#erreurs) |
| `invalid_request` | 400, 413 | Conversation | [Modèle](https://realmoon.ai/documentation/api/erreurs/#modele) |
| `invalid_request_error` | 400 | Médias | [Modèle](https://realmoon.ai/documentation/api/erreurs/#modele) |
| `invalid_value` | 400 | Tous | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `ip_not_allowed` | 403 | Tous | [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle) |
| `job_not_recorded` | 503 | Vidéos | [Vidéos](https://realmoon.ai/documentation/api/videos/#erreurs) |
| `length_required` | 411 | Envois multipart | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `method_not_allowed` | 405 | Tous | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `missing_required_parameter` | 400 | Tous | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `missing_scope` | 403 | Tous | [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle) |
| `model_not_found` | 404 | Tous ceux qui prennent un `model` | [Modèle](https://realmoon.ai/documentation/api/erreurs/#modele) |
| `model_rate_limited` | 429 | Conversation | [Trop de requêtes](https://realmoon.ai/documentation/api/erreurs/#debit) |
| `moon_blur_payload_too_large` | 413 | Conversation, embeddings | [Moon Blur](https://realmoon.ai/documentation/api/erreurs/#moon-blur) |
| `moon_blur_unavailable` | 503 | Conversation, embeddings | [Moon Blur](https://realmoon.ai/documentation/api/erreurs/#moon-blur) |
| `n_not_supported` | 400 | Conversation | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `no_available_route` | 400, 413 | Conversation | [Modèle](https://realmoon.ai/documentation/api/erreurs/#modele) |
| `ocr_busy` | 503 | OCR | [OCR](https://realmoon.ai/documentation/api/ocr/) |
| `ocr_timeout` | 504 | OCR | [OCR](https://realmoon.ai/documentation/api/ocr/) |
| `org_policy` | 403 | Tous ceux qui prennent un `model` | [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle) |
| `org_policy_unavailable` | 503 | Tous ceux qui prennent un `model`, liste des modèles | [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle) |
| `pricing_unavailable` | 503 | Conversation | [Modèle](https://realmoon.ai/documentation/api/erreurs/#modele) |
| `rate_limit_exceeded` | 429 | Tous | [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle) |
| `request_too_large` | 413 | Médias | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `service_unavailable` | 503 | Tous | [Clé et accès](https://realmoon.ai/documentation/api/erreurs/#cle) |
| `spend_cap_exceeded` | 402 | Tous ceux qui sont facturés | [Crédits et plafonds](https://realmoon.ai/documentation/api/erreurs/#credits) |
| `string_above_max_length` | 400 | Images, vidéos, voix | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `too_many_concurrent` | 429 | Médias | [Trop de requêtes](https://realmoon.ai/documentation/api/erreurs/#debit) |
| `too_many_images` | 400 | Retouche d’images | [Images](https://realmoon.ai/documentation/api/images/#erreurs) |
| `too_many_pages` | 400 | OCR | [OCR](https://realmoon.ai/documentation/api/ocr/) |
| `unknown_parameter` | 400 | Médias | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `unknown_url` | 404 | Tous | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `unreadable_document` | 422 | OCR | [OCR](https://realmoon.ai/documentation/api/ocr/) |
| `unsupported_content` | 400 | Conversation | [Conversation](https://realmoon.ai/documentation/api/chat/#messages) |
| `unsupported_format` | 400 | Transcription, OCR | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `unsupported_model` | 400 | Retouche d’images | [Images](https://realmoon.ai/documentation/api/images/#erreurs) |
| `unsupported_parameter` | 400 | Tous | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `unsupported_value` | 400 | Médias | [Requête](https://realmoon.ai/documentation/api/erreurs/#requete) |
| `upstream_error` | 502, autres 5xx | Tous ceux qui appellent un modèle | [Modèle en panne et service](https://realmoon.ai/documentation/api/erreurs/#service) |
| `upstream_rate_limited` | 429 | Médias | [Trop de requêtes](https://realmoon.ai/documentation/api/erreurs/#debit) |
| `upstream_timeout` | 504 | Tous ceux qui appellent un modèle | [Modèle en panne et service](https://realmoon.ai/documentation/api/erreurs/#service) |
| `upstream_unavailable` | 503 | Médias | [Modèle en panne et service](https://realmoon.ai/documentation/api/erreurs/#service) |
| `url_not_supported` | 400 | OCR | [OCR](https://realmoon.ai/documentation/api/ocr/) |
| `video_expired` | 410 | Téléchargement de vidéo | [Vidéos](https://realmoon.ai/documentation/api/videos/#telecharger) |
| `video_not_found` | 404 | Suivi et téléchargement de vidéo | [Vidéos](https://realmoon.ai/documentation/api/videos/#suivre) |
| `video_not_ready` | 409 | Téléchargement de vidéo | [Vidéos](https://realmoon.ai/documentation/api/videos/#telecharger) |

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](https://realmoon.ai/documentation/api/videos/#objet).

---

Documentation Moon AI › API développeur › Erreurs. Page : https://realmoon.ai/documentation/api/erreurs/. Modifiée le 5 novembre 2026.

© 2026 Stellarr Studio SAS. Tous droits réservés. Moon AI, Moon Blur et Stellarr Studio sont des marques déposées à l’INPI.