Codes d'erreur
Un appel en échec utilise la même enveloppe qu'un appel réussi : lisez le code de statut HTTP, puis lisez response pour obtenir un message décrivant ce qui n'a pas fonctionné. Les messages sont des chaînes anglaises stables, vous pouvez donc vous appuyer dessus, mais préférez le code de statut pour vos branchements.
{
"code": 403,
"title": "Forbidden",
"response": "The API key is missing the required scope: team:write"
}Codes de statut
| Code | Intitulé | Signification |
|---|---|---|
| 200 | OK | L'appel a réussi. Les lectures, les modifications et les suppressions utilisent tous ce code. |
| 201 | Created | Un enregistrement a été créé. Utilisé par les appels key, team et feedback. |
| 301 | Moved Permanently | Vous avez appelé en http://. Refaites l'appel en https://. |
| 400 | Bad Request | Le corps n'était pas un objet JSON, ou un champ obligatoire était absent. |
| 401 | Unauthorized | Aucune clé utilisable n'a été présentée, ou la clé a expiré. |
| 402 | Payment Required | L'abonnement ne couvre pas l'action, ou son quota est épuisé. |
| 403 | Forbidden | La clé est inconnue, désactivée, ou n'a pas la portée exigée. |
| 404 | Not Found | Chemin inexistant, ou enregistrement inexistant dans ce projet. |
| 405 | Method Not Allowed | La méthode n'est pas acceptée sur ce chemin. |
| 413 | Payload Too Large | Le corps de la requête dépassait 200 000 octets. |
| 422 | Unprocessable entity | Le corps a été analysé mais une valeur a été rejetée, ou la méthode et le chemin ne se combinent pas. |
| 501 | Not Implemented | L'appel est réservé et n'agit pas encore. |
| 503 | Service Unavailable | Un service sous-jacent était brièvement injoignable. Réessayez. |
| 500 | Internal Server Error | Une anomalie inattendue. Réessayez, puis signalez-la. |
Échecs d'authentification
Ils sont levés avant l'exécution du code de tout appel : 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, ou ne commence pas par Bearer . |
| 401 | The API key has expired. | La clé avait une date d'expiration et celle-ci est passée. Une clé sans expiration ne lève jamais ce message. |
| 403 | The API key doesn't have permissions to perform the request. | La clé est inconnue, ou elle est désactivée, ou son consommateur ou son projet n'est plus actif. |
Note — Une clé inconnue et une clé désactivée donnent le même
403avec le même message, volontairement : l'API ne confirme jamais si une clé existe.
Échecs de portée
Un appel vérifie sa portée avant d'effectuer le moindre travail.
| Code | Message | Cause |
|---|---|---|
| 403 | The API key is missing the required scope: <portée> | La clé ne détient ni *, ni <ressource>:*, ni la portée exacte nommée. |
| 403 | Cannot create a key with wider scope than the calling key. | Vous avez demandé * sur une nouvelle clé alors que votre propre clé est plus restreinte. |
Le message nomme la portée attendue : la correction consiste donc soit à élargir la clé, soit à cesser d'appeler cet appel. Voir Clés API.
Échecs de requête
| Code | Message | Cause |
|---|---|---|
| 400 | Invalid JSON. | Le corps n'est pas du JSON analysable, 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 se combinent pas en un appel pris en charge, ou une valeur a été rejetée sans message plus précis. |
Introuvable
Il existe deux 404 différents, et ils sont faciles à distinguer.
Un chemin inconnu est refusé par la passerelle, avant d'atteindre le moindre appel. Celui-ci répète code sous forme de chaîne plutôt que de nombre :
{
"code": "404",
"title": "Not Found",
"response": "The requested resource was not found."
}Un chemin qui existe mais qui nomme un enregistrement que votre projet ne peut pas voir est refusé par l'appel lui-même, avec un message nommant le type d'enregistrement — App not found., Event not found., File not found., API key not found., Team member not found., Feedback not found., Reasoning not found. ou Public app not found.
Important — Un enregistrement qui appartient à un autre projet renvoie le même
404qu'un enregistrement qui n'a jamais existé. C'est ce qui rend une clé sûre à confier à un tiers : elle ne permet pas de découvrir ce que contiennent les autres projets.
Échecs d'abonnement et de quota
Les appels run et app vérifient l'abonnement du projet avant d'agir.
| Code | Intitulé | 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. |
Appelez GET /v1/run-usage/summary pour lire le quota restant avant de lancer une exécution, et pour savoir quand le cycle se réinitialise.