# Erreurs

Source: https://docs.aicentos.com/fr/billing/errors

Language: fr

> Codes de statut HTTP, structure des réponses d’erreur, erreurs courantes et solutions

aicentos reprend intégralement le **format de réponse d’erreur d’OpenAI**. Quand un SDK lève une erreur, il suffit d’intercepter l’exception correspondante.

## Structure d’une réponse d’erreur

Toutes les réponses d’erreur suivent ce format :

```bash
{
  "error": {
    "message": "Votre clé API n’a pas accès à gpt-5",
    "type": "permission_denied",
    "code": "model_not_allowed",
    "param": "model"
  }
}
```

| Champ     | Signification                                        |
| --------- | ---------------------------------------------------- |
| `message` | Description de l’erreur, lisible par un humain       |
| `type`    | Catégorie d’erreur (voir tableau ci-dessous)         |
| `code`    | Code d’erreur détaillé (pour la logique applicative) |
| `param`   | Nom du champ en erreur (le cas échéant)              |

## Codes de statut HTTP en bref

| Code  | Type                     | Causes courantes                                                                |
| ----- | ------------------------ | ------------------------------------------------------------------------------- |
| `400` | `invalid_request_error`  | corps de requête mal formé, paramètre invalide, nom de `model` mal orthographié |
| `401` | `authentication_error`   | clé API absente / erronée / révoquée                                            |
| `402` | `insufficient_quota`     | solde insuffisant                                                               |
| `403` | `permission_denied`      | clé désactivée, modèle non autorisé, IP hors liste blanche                      |
| `404` | `not_found`              | chemin d’endpoint erroné, ID de modèle erroné                                   |
| `408` | `request_timeout`        | délai d’attente amont (généralement > 60 s sans réponse)                        |
| `413` | `payload_too_large`      | corps de requête trop volumineux (image, fichier)                               |
| `415` | `unsupported_media_type` | Content-Type incorrect                                                          |
| `422` | `invalid_request_error`  | corps de requête analysable mais sémantiquement incorrect                       |
| `429` | `rate_limit_exceeded`    | limite de débit déclenchée ; réduisez la fréquence puis réessayez               |
| `500` | `server_error`           | erreur interne de la plateforme (rare)                                          |
| `502` | `bad_gateway`            | service amont en anomalie                                                       |
| `503` | `service_unavailable`    | amont surchargé ; réessayez plus tard                                           |
| `504` | `gateway_timeout`        | délai dépassé côté amont                                                        |

## Erreurs courantes et solutions

### 401 — Invalid API key

```bash
{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }
```

**Liste de vérification** :

* l’en-tête `Authorization` respecte bien le format `Bearer sk-xxx` (attention à l’espace)
* la clé copiée depuis la console n’embarque pas d’espace ni de saut de ligne
* la clé n’est ni supprimée, ni désactivée, ni expirée
* une clé de test n’a pas été poussée en production

### 402 — Insufficient quota

```bash
{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }
```

Rechargez → console, « Gestion du portefeuille ». Activez l’[alerte de solde](https://docs.aicentos.com/fr/billing/pricing#alerte-de-solde) pour éviter que cela se reproduise.

### 403 — Model not allowed

```bash
{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }
```

À la création du jeton, une liste blanche « **Modèles autorisés** » a été cochée et le `model` demandé n’en fait pas partie. Modifiez les réglages du jeton ou changez de clé.

### 404 — Model not found

```bash
{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }
```

ID de modèle mal orthographié ou retiré. Vérifiez les ID actuellement disponibles dans le [catalogue des modèles](https://aicentos.com/pricing).

### 429 — Rate limit exceeded

L’en-tête `Retry-After` indique au bout de combien de secondes réessayer. Réduisez la concurrence et la fréquence des requêtes pour revenir à la normale.

### 500 / 502 / 503 — Erreur de service

Généralement une instabilité amont. **2 à 3 tentatives automatiques** suffisent souvent. Si cela dure plus de 5 minutes :

* consultez la [page de statut](https://status.aicentos.com) (si disponible)
* contactez le support

### 408 / 504 — Délai dépassé

Aucune réponse au bout de 60 s. Causes fréquentes :

* prompt trop long : la « réflexion » du modèle dépasse le délai imparti
* sortie en streaming non activée (ajoutez `stream: true` pour les réponses longues)

**Solutions** :

* raccourcissez le prompt
* activez le streaming : `{ "model": "...", "messages": [...], "stream": true }`
* passez à un modèle plus rapide (par exemple de `gpt-4o` à `gpt-4o-mini`)

## Exemple de gestion des erreurs en SDK

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"
```

### Python

```python
import os
from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1")

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
    )
except AuthenticationError:
    print("Clé incorrecte")
except RateLimitError as e:
    print(f"Limite de débit atteinte, nouvelle tentative dans {e.response.headers.get('Retry-After')} s")
except APIError as e:
    print(f"Autre erreur API : {e.status_code} {e.message}")
```

### Node.js

```js
import OpenAI, { APIError } from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

try {
  const resp = await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.code, err.message);
  }
}
```

## Réessais et repli

| Type d’erreur                         | Traitement recommandé                                                    |
| ------------------------------------- | ------------------------------------------------------------------------ |
| `400` / `401` / `402` / `403` / `404` | **pas de réessai** : erreur de code / de configuration, corrigez d’abord |
| `429`                                 | réessayez selon `Retry-After`, avec backoff exponentiel                  |
| `500` / `502` / `503` / `504` / `408` | réessayez immédiatement 1 à 3 fois, espacées de 1 à 5 s                  |

Les SDK officiels OpenAI embarquent par défaut une politique de réessai raisonnable ; **en production, passez par le SDK plutôt que par vos propres appels fetch**.