Codes d'erreur de l'API IA
Un appel en échec utilise la même enveloppe qu'un appel réussi : lisez le code de statut HTTP, puis lisez response pour un message qui décrit le problème. Les messages sont des phrases anglaises stables que vous pouvez journaliser et reconnaître, mais décidez d'après le code de statut.
{
"code": 403,
"title": "Forbidden",
"response": "The API key is missing the required scope: reasoning:write"
}Codes de statut
| Code | Titre | Signification |
|---|---|---|
| 200 | OK | L'appel a réussi. Les lectures, modifications, révocations et créations d'applications et d'exécutions utilisent ce code. |
| 201 | Created | Une clé a été créée. |
| 301 | Moved Permanently | Vous avez appelé http://. Refaites l'appel en https://. |
| 400 | Bad Request | Le corps n'était pas un objet JSON, un champ obligatoire manquait ou une valeur avait le mauvais type. |
| 401 | Unauthorized | Aucune clé utilisable n'a été présentée, ou la clé a expiré. |
| 402 | Payment Required / Quota exceeded | Le forfait ne couvre pas l'action, ou son allocation de jetons est épuisée. |
| 403 | Forbidden | La clé est inconnue, suspendue ou révoquée, ou il lui manque le droit requis. |
| 404 | Not Found | Ce chemin n'existe pas, ou cet élément n'existe pas dans votre projet. |
| 413 | Payload Too Large | Le corps de la requête dépassait 200 000 octets. |
| 422 | Unprocessable entity | Le corps a été lu mais une valeur a été refusée, ou la méthode et le chemin ne forment pas un point d'accès. |
| 429 | Too Many Requests | Trop de requêtes en peu de temps. Attendez le nombre de secondes indiqué par l'en-tête Retry-After, puis réessayez. |
| 500 | Internal Server Error | Une erreur inattendue. Réessayez, puis signalez-la. |
| 503 | Service Unavailable | Le service IA est momentanément indisponible. Réessayez plus tard. |
Échecs d'authentification
Ils sont vérifiés avant tout le reste, ils peuvent donc répondre sur n'importe quel chemin.
| Code | Message | Cause |
|---|---|---|
| 401 | No valid API key provided. | L'en-tête Authorization est absent, ne commence pas par Bearer ou ne porte pas de clé de projet. |
| 401 | The API key has expired. | La clé avait une date d'expiration et elle est passée. Une clé sans date d'expiration ne produit jamais ce message. |
| 403 | The API key doesn't have permissions to perform the request. | La clé est inconnue, suspendue ou révoquée, ou son projet n'est plus actif. |
Remarque — Une clé inconnue et une clé révoquée reçoivent le même
403avec le même message, volontairement : l'API ne confirme jamais l'existence d'une clé.
Échecs de droits
Un point d'accès vérifie son droit avant tout traitement.
| Code | Message | Cause |
|---|---|---|
| 403 | The API key is missing the required scope: <scope> | La clé ne détient ni *, ni <ressource>:*, ni le droit exact nommé. |
| 403 | Cannot create a key with wider scope than the calling key. | Vous avez demandé * pour une nouvelle clé alors que votre propre clé est plus restreinte. |
Le message nomme le droit attendu : utilisez une clé qui le détient, ou cessez d'appeler ce point d'accès. Voir Clés de l'API IA.
Échecs de requête
| Code | Message | Cause |
|---|---|---|
| 400 | Invalid JSON. | Le corps n'est pas du JSON lisible, ou c'est une valeur JSON qui n'est pas un objet. |
| 413 | Request body too large. | Le corps dépassait 200 000 octets. |
| 422 | The parameters were valid but the request failed. | La méthode et le chemin ne forment pas un point d'accès (par exemple DELETE sur une application), ou une valeur a été refusée sans message plus précis. |
Introuvable
Il existe deux 404 différents. Un chemin inconnu est refusé avant d'atteindre un point d'accès :
{
"code": 404,
"title": "Not Found",
"response": "The requested resource was not found."
}Un chemin qui existe mais désigne un élément que votre projet ne peut pas voir est refusé par le point d'accès, avec un message qui nomme le type d'élément : App not found., Reasoning not found. ou API key not found.
Important — Une exécution ou une clé qui appartient à un autre projet renvoie le même
404qu'un élément qui n'a jamais existé : une clé ne permet donc pas de découvrir ce que contiennent les autres projets.
Échecs de forfait et de quota
Les points d'accès des exécutions et des applications vérifient le forfait de votre projet avant d'agir.
| Code | Titre | Message |
|---|---|---|
| 402 | Quota exceeded | Your reasoning quota is exhausted. Please wait until it resets or upgrade your plan. |
| 402 | Payment Required | The current billing plan does not allow custom app creation for this project. |
| 402 | Payment Required | The current billing plan app limit has been reached for this project. |
| 402 | Payment Required | The selected model library is not available for the current billing plan. |
Appelez GET /v1/ai/run-usage/summary pour lire l'allocation restante avant de lancer une exécution, et pour savoir quand le cycle repart à zéro. Voir Quota et consommation de jetons IA.