Erreurs

Trois couches d’erreur

Shape JSON courante

{
  "error": "Message lisible"
}

C’est le format le plus fréquent pour les erreurs de validation, authentification, autorisation et indisponibilité simple.

Ce format n’est pas universel : Connectors possède ses propres erreurs métier et GET /api/auth/session retourne actuellement { "user": null } sur 401.

Codes HTTP observés

400 — Bad Request

Un 400 signifie généralement que la requête doit être corrigée avant d’être rejouée.

Exemples AI :

Unknown OrbitWake model.
Unknown OrbitWake mode.
Invalid message.
Invalid message role.
Message content cannot be empty.
System messages are managed by OrbitWake and cannot be supplied by clients.
Only user messages can contain attachments.
Invalid conversation.

Exemples Connectors :

Invalid JSON.
connectorId and actionName are required.
idempotencyKey must be a string.
approvalId must be a valid UUID.
decision must be approve or deny.

401 — Authentification

Les deux messages principaux observés sont :

Authentication required.
IDE authentication required.

Le premier concerne principalement les routes web protégées par la session OrbitWake. Le second concerne les routes IDE protégées par un Bearer token dédié.

Un retry avec le même credential invalide ne résoudra pas le problème : il faut rétablir une session valide ou refaire le pairing IDE.

403 — Authentifié mais non autorisé

Exemples :

OrbitWake AI is not available for this account.
OrbitWake IDE AI is not available for this account.
OrbitWake IDE Agent is not available for this account.
This workspace does not have active private beta access.
Private beta access has expired.

Dans Connectors, INVALID_APPROVAL est mappé vers 403 lorsque l’approval ne correspond pas à l’action exacte ou n’est plus valide.

404 — Ressource absente

Exemples confirmés :

Conversation not found.
Project not found.
Version not found.
Memory not found.
Approval not found, expired, or already decided.

La couche Projects utilise aussi 404 lorsque la private beta est entièrement désactivée : Private beta projects are not enabled.

409 — Conflit d’état

Projects utilise 409 pour des conflits métier comme :

This beta workspace is limited to N active projects.
Unable to allocate a unique project name.

Le client doit généralement modifier l’état ou la demande avant de réessayer.

413 — Payload trop volumineux

AI utilise 413 pour :

Each attachment must be 8 MB or smaller.
Attach at most 3 files to a message.
Attachments in the conversation context exceed 12 MB.
Conversation context is too large.

Projects utilise également 413 lorsqu’un fichier dépasse la limite beta ou que le stockage total du projet serait dépassé.

429 — Rate limit

La recherche de domaine peut répondre :

{
  "error": "Too many domain searches. Please try again shortly."
}

Le endpoint renvoie aussi :

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After

Le client doit respecter Retry-After plutôt que relancer immédiatement.

AI — validation et limites

Les erreurs AI de validation utilisent AiGatewayError avec un status explicite.

Exemples :

Unsupported attachment. Use PDF, PNG, JPEG, WEBP, or GIF.
Attachments currently require OrbitWake Auto or OpenAI.
Live web search currently requires OrbitWake Auto or OpenAI.
Qwen is disabled for this private test.

Le gateway peut aussi refuser une requête si un provider requis n’est pas configuré.

AI — mapping des erreurs provider

Les providers OpenAI, Anthropic et compatibles convertissent actuellement :

Le champ interne retryable sert notamment au fallback OrbitWake Auto avant émission d’un premier delta.

AI — budget provider quotidien

503
{
  "error": "OrbitWake AI daily provider budget has been reached."
}

Cette erreur n’indique pas un problème de payload ou d’authentification. Elle vient d’une limite serveur globale de coût provider.

AI — fallback 500

Si une erreur inattendue n’est pas déjà une AiGatewayError, les routes AI renvoient généralement :

500
{
  "error": "OrbitWake AI is temporarily unavailable."
}

Streaming — erreur avant ou après ouverture

Avant ouverture du SSE, le status HTTP réel est utilisé normalement.

Après ouverture du HTTP 200, une erreur devient un événement :

event: error
data: {
  "error": "Message lisible",
  "status": 503
}

Le champ status est alors logique : le status HTTP du flux reste déjà fixé à 200.

Projects — erreurs private beta

La couche Projects encapsule ses erreurs métier avec PrivateBetaError.

Exemples :

Project name is required.
Project name must be between 1 and 120 characters.
File path is invalid.
File content must be text.
Private beta projects are not enabled.
Finish workspace setup before using beta projects.
This workspace does not have active private beta access.
Private beta access has expired.
Project not found.
Version not found.

Les handlers conservent le status fourni par PrivateBetaError. Les erreurs inattendues deviennent un 500 avec un message fallback spécifique à l’opération.

Memory

Memory utilise principalement 400, 401 et 404.

Memory content is required.
Unknown memory scope.
Unknown memory category.
Project memories require a project name or key.
Title cannot be empty.
Content cannot be empty.
Memory not found.

Une exception levée pendant create/update est actuellement convertie en 400 avec le message de l’exception lorsqu’il existe.

Connectors — erreurs métier

Connectors peut répondre avec une structure :

{
  "result": {
    "success": false,
    "error": {
      "code": "ACTION_NOT_FOUND",
      "message": "...",
      "retryable": false
    }
  },
  "approval": null,
  "requestId": "uuid",
  "activity": [...]
}

Codes métier confirmés dans le bridge actuel :

Connectors — erreur serveur

Si le handler lui-même échoue :

500
{
  "error": "Connector action could not be completed."
}

Ce cas est différent d’un result.success = false métier correctement produit par le bridge.

IDE

Erreurs courantes :

IDE authentication required.
OrbitWake IDE AI is not available for this account.
OrbitWake IDE Agent is not available for this account.
Prompt is required.
No readable workspace files were supplied.
Pairing code is invalid or expired.
Invalid JSON.

Le endpoint Agent peut aussi remonter des erreurs de proposition comme :

OrbitWake did not return a valid patch proposal.
Invalid patch proposal.
OrbitWake did not propose any applicable file changes.

Domains

Les erreurs provider domaine utilisent DomainProviderError avec un status propre, par défaut 502.

Une erreur inattendue devient :

500
{
  "error": "Domain search is temporarily unavailable."
}

Le endpoint conserve ses headers de rate limit même lors des erreurs.

Health

/api/health ne transforme pas chaque composant dégradé en objet { error }. Il agrège l’état des composants.

Si un ou plusieurs checks échouent, la réponse globale utilise status: "degraded" avec HTTP 503.

Les erreurs internes de composants sont loggées côté serveur et représentées par leur état agrégé.

Quand réessayer

Backoff recommandé

L’API actuelle ne publie pas encore une politique de retry globale.

Pour les erreurs transitoires sans Retry-After, utilisez un backoff exponentiel borné avec jitter côté client, et limitez le nombre de tentatives.

Pour les POST mutatifs, vérifiez d’abord si l’opération possède une idempotency explicite. Connectors accepte idempotencyKey dans son body ; ce mécanisme n’est pas global à toute l’API.

Erreurs à ne pas rejouer aveuglément

• création de projet après timeout sans vérifier si le projet existe déjà ;
• création de memory après interruption réseau ;
• création de checkpoint sans connaître le résultat précédent ;
• actions Connector mutatives sans idempotency appropriée ;
• POST ayant pu être traité côté serveur avant la perte de connexion.

Pattern client

const response = await fetch(url, options);

if (!response.ok) {
  const payload = await response.json().catch(() => ({}));
  const message =
    typeof payload.error === "string"
      ? payload.error
      : `OrbitWake request failed (${response.status})`;

  throw new Error(message);
}

const payload = await response.json();

Pour Connectors et SSE, un traitement supplémentaire est nécessaire car l’échec peut être représenté autrement qu’un simple !response.ok.

Logs et diagnostic

Lors d’un bug, capturez au minimum :

• route et méthode ;
• status HTTP ;
• message d’erreur ;
• timestamp ;
• requestId si la surface en fournit un ;
• mode/modèle pour AI ;
• action Connector si concernée.

Ce qui n’est pas encore standardisé

• pas de code d’erreur machine global sur toutes les routes ;
• pas de requestId global ;
• pas de champ retryable universel ;
• pas de structure unique { error: { code, message } } ;
• pas de politique de retry externe versionnée ;
• pas de catalogue public exhaustif des erreurs.

Limites actuelles

Les messages et mappings décrits ici correspondent au runtime actuel. Une future API publique versionnée devra stabiliser les codes machine, les envelopes, le request tracing et la politique de retry avant d’être considérée comme contrat externe durable.

Étape suivante

La page Limites documentera les quotas, tailles maximales, contraintes de contexte, limites Projects, Memory, Connectors, IDE et rate limits vérifiés aujourd’hui.