Erreurs

Format des erreurs, codes de réponse des deux API, et quoi vérifier pour chacun.

Format

Toute erreur renvoie un corps JSON de la même forme :

{
  "statusCode": 403,
  "message": "The token does not grant a required scope.",
  "error": "Forbidden"
}

message est destiné au développeur, pas à l'utilisateur final : il décrit la cause, en anglais, et peut être un tableau sur une erreur de validation (une entrée par champ fautif).

API Third-Party

Codes de réponse

Code	Quand	Quoi vérifier
`400`	Corps ou paramètres invalides	Le `message` liste les champs. Une propriété inconnue est refusée, pas ignorée — voir Conventions.
`401`	Jeton absent, invalide ou expiré	L'en-tête `Authorization: Bearer …` ; la signature, `iss`, `aud`, `exp` du JWT. Un access token issu du flow sans `resource` échoue ici.
`403`	Jeton valide, mais insuffisant	Voir le 403 en détail ci-dessous.
`404`	Ressource introuvable	L'identifiant vient-il bien d'une réponse précédente, dans la même organisation que le jeton ?
`409`	Conflit d'état	L'opération n'est pas possible dans l'état courant (item déjà acheté, clé déjà révoquée…). Le `message` précise.
`429`	Quota atteint	L'utilisateur n'a plus d'orbs pour une route qui en consomme — voir la colonne Orbs des Scopes.
`5xx`	Erreur côté Oreus	Réessayez avec un délai croissant ; si ça persiste, signalez-le avec l'heure et la route.

Le 403 en détail

C'est le code le plus fréquent en intégration, et il a trois causes distinctes que le message permet de séparer.

Message	Cause	Correction
`The access token does not identify its client application.`	Le jeton n'a pas de `client_id` — il n'a pas été émis pour une application.	Utilisez le jeton obtenu par le flow OIDC de votre application, pas un jeton de la console.
`This resource is only accessible with a third-party application token.`	L'application émettrice n'est pas de type Third-party.	Le type ne se change pas après coup : créez une application third-party.
`The token does not grant a required scope.`	Le scope exigé par la route n'est pas dans le jeton.	Vérifiez qu'il est déclaré dans Permissions et demandé dans `scope` à la connexion. Puis reconnectez l'utilisateur : un jeton existant n'acquiert pas de nouveaux scopes.

Pour savoir ce que porte réellement un jeton, décodez son payload (sans le vérifier — c'est un outil d'affichage) et lisez le claim scope. Comparez à ce que vous avez demandé : la différence, ce sont les scopes non déclarés côté console, ignorés en silence.

Jeton d'organisation manquant

Un access token issu directement du flow (étape 2 du Démarrage rapide) porte l'audience de l'API mais pas de contexte d'organisation. Selon la route, l'échec se manifeste par un 401 ou un 403. Dans les deux cas, la réponse est la même : échanger le refresh token avec organization_id — voir Jeton d'organisation.

API Inférence

Deux jetons peuvent entrer en jeu — la clé API, obligatoire, et le jeton utilisateur, optionnel. La première question devant une erreur est donc : lequel des deux est refusé ? Le message le dit : les erreurs d'authentification portent un code stable (API_KEY_INVALID, USER_TOKEN_MISSING_INFERENCE_SCOPE…), les autres une phrase.

Clé API (`Authorization`)

Code	`message`	Cause
`401`	`API_KEY_MISSING`	Pas d'en-tête `Authorization`.
`401`	`API_KEY_INVALID`	La clé n'existe pas ou a été révoquée. Un JWT OIDC à cet endroit donne aussi cette erreur : la clé API et le jeton utilisateur ne se mettent pas dans le même en-tête.
`404`	`Agent not found`	Le `model` n'est pas un agent de cette agent key.
`409`	`Key format not supported`	Type de clé inconnu.
`409`	`Embeddings endpoint is only available with a Model API key`	`/embeddings` appelé avec une agent key.

Jeton utilisateur (`x-oreus-user-authorization`)

Présent, il doit remplir toutes les conditions ; sinon la requête est refusée, jamais rabattue sur l'organisation.

Code	`message`	Cause	Correction
`401`	`USER_TOKEN_INVALID: …`	Signature, `iss`, `aud` ou `exp` invalide. Le détail suit le deux-points.	Rafraîchir le jeton ; vérifier `resource` à la connexion.
`403`	`USER_TOKEN_HAS_NO_CLIENT`	Le jeton n'a pas de `client_id`.	Utiliser un jeton issu du flow OIDC d'une application.
`403`	`USER_TOKEN_NOT_ISSUED_TO_A_THIRD_PARTY_APPLICATION`	L'application émettrice n'est pas de type third-party.	Créer une application third-party.
`403`	`USER_TOKEN_MISSING_INFERENCE_SCOPE`	Le jeton ne porte ni `read:inference` ni `write:inference`.	Déclarer le scope dans Permissions et le demander à la connexion, puis reconnecter l'utilisateur.
`403`	`USER_TOKEN_MISSING_ORGANIZATION`	Access token du flow, sans contexte d'organisation.	Échanger le refresh token avec `organization_id` — Jeton d'organisation.
`403`	`APPLICATION_NOT_REGISTERED`	L'application émettrice n'est rattachée à aucune organisation.	Vérifier l'enregistrement de l'application dans la console.
`403`	`API_KEY_NOT_OWNED_BY_APPLICATION_ORGANIZATION`	La clé appartient à une autre organisation que celle de l'application.	Utiliser une clé créée par l'organisation qui possède l'application.
`429`	`TIER_TOKEN_LIMIT_REACHED`	L'utilisateur n'a plus d'orbs.	Il doit en racheter ; ou retirer l'en-tête pour facturer l'organisation.

Requête

Code	Cause
`400`	Corps invalide. Avec une agent key, seuls `messages`, `model`, `stream`, `stream_options` et `files` sont acceptés ; le reste vient de la configuration de l'agent. Avec une model key, le corps est transmis tel quel et la validation est celle du fournisseur.
`400`	Fichier refusé sur `/files` : type non pris en charge ou plus de 512 Mo — voir Fichiers.

En streaming

Une fois le flux ouvert, le code HTTP reste 200 : les erreurs de génération arrivent dans le flux, sous la forme { "error": { "message", "type" } } — voir Streaming.

Erreurs

Sur cette page