Dépannage

Les 60 premières secondes

1. Notez l’action exacte qui échoue.
2. Copiez le message d’erreur exact.
3. Notez le status HTTP lorsqu’il existe.
4. Identifiez la surface : CLI, VS Code, API, Connector, Projects, Memory ou route publique.
5. Vérifiez si le problème est local, lié au compte, à l’autorisation ou au service distant.

Quel guide ouvrir ?

Vérifier si le service répond

Avant de modifier votre machine, vérifiez si OrbitWake lui-même est opérationnel.

GET https://orbitwake.com/api/health

Le endpoint retourne 200 lorsque les composants vérifiés sont opérationnels et 503 lorsque l’état agrégé est degraded.

Vous pouvez aussi consulter status.orbitwake.com pour un état public du service.

401 ou perte de session

Deux familles d’authentification existent aujourd’hui :

• session web OrbitWake pour les routes produit ;
• Bearer token IDE dédié pour VS Code.

Messages courants :

Authentication required.
IDE authentication required.

Un retry avec le même credential invalide ne résout généralement rien. Rétablissez la session web ou refaites le pairing IDE selon la surface concernée.

403 : authentifié mais non autorisé

Un 403 signifie généralement que l’identité est reconnue mais que l’action n’est pas disponible dans ce contexte.

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.

Ne recréez pas une session en boucle si le problème est l’éligibilité, la beta ou une permission Connector.

413 : requête trop grande

Réduisez le payload plutôt que de relancer la même requête.

Limites AI structurantes :

• 3 pièces jointes maximum par message ;
• 8 MB maximum par fichier ;
• 12 MB maximum pour les pièces jointes du contexte ;
• 30 messages et 60 000 caractères par requête par défaut de policy.

Projects private beta limite actuellement un fichier à 512 KB.

429 : rate limit

La recherche de domaine renvoie Retry-After lorsqu’elle refuse temporairement une requête.

if (response.status === 429) {
  const retryAfter =
    response.headers.get("Retry-After");

  console.log(retryAfter);
}

N’utilisez pas de boucle agressive. Attendez la durée indiquée et réessayez ensuite.

502 / 503 / 504 : provider ou service distant

Un retry borné peut être pertinent sur ces erreurs transitoires. Évitez cependant de rejouer automatiquement une opération persistante si vous ne savez pas si le serveur l’a déjà traitée.

Streaming AI qui s’interrompt

Avant ouverture du stream, une erreur utilise son status HTTP normal. Après ouverture du HTTP 200, l’erreur arrive comme événement SSE :

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

Si du texte partiel a déjà été reçu, le client officiel peut conserver cette réponse et l’afficher comme interrompue.

Le parser doit bufferiser jusqu’à \n\n avant de parser un événement complet.

VS Code : pairing ou Agent ne fonctionne pas

Vérifiez dans cet ordre :

1. VS Code 1.106 ou plus récent ;
2. extension OrbitWake activée ;
3. workspace/dossier ouvert pour Agent ;
4. pairing code non expiré ;
5. session IDE non révoquée ;
6. compte autorisé pour IDE AI / Agent ;
7. fichiers non sensibles et lisibles ;
8. proposition toujours valide par rapport aux fichiers locaux.

Si un fichier a changé après la création d’un patch, OrbitWake doit refuser un Apply obsolète plutôt que d’écraser silencieusement la nouvelle version.

CLI : la commande ou le contexte semble incorrect

Commencez par des vérifications non destructives :

pwd
npm --version
git status
git branch --show-current

Puis lancez OrbitWake depuis le répertoire réellement concerné.

Ne lancez pas git reset, git clean ou un changement de PATH au hasard pour résoudre un problème dont la cause n’est pas encore identifiée.

GitHub Connector : connecté mais action refusée

Le Connector GitHub distingue :

• read — autorisé par défaut ;
• write — demande une approval par défaut ;
• sensitive — demande une approval explicite.

Une action write peut donc retourner 202 avec APPROVAL_REQUIRED au lieu d’être exécutée immédiatement.

Une approval expire après 10 minutes, n’est utilisable qu’une fois et est liée aux paramètres exacts de l’action.

GitHub affiche “Connect” alors qu’une installation existe

Séparez trois états différents :

1. installation GitHub App côté GitHub ;
2. credential/connecteur enregistré dans OrbitWake ;
3. lecture runtime réellement fonctionnelle.

Une installation GitHub existante ne garantit pas à elle seule que le Connector OrbitWake est chargé et utilisable. La page GitHub décrit également que Disconnect OrbitWake n’est pas équivalent à désinstaller l’app côté GitHub.

Projects private beta

Les erreurs typiques concernent l’accès beta, la limite de projets ou la taille de fichier.

Private beta projects are not enabled.
This workspace does not have active private beta access.
Private beta access has expired.
Project not found.

Les defaults DB inspectés sont 3 projets actifs et 5 MB de stockage projet, mais ces valeurs peuvent être différentes pour un workspace donné.

Memory : entrée absente ou non retrouvée

Vérifiez :

• le scope : personal, workspace ou project ;
• la project key pour une memory project ;
• le contenu, qui ne peut pas être vide ;
• la catégorie utilisée ;
• la recherche et le contexte envoyé à AI.

Une memory peut exister sans être sélectionnée parmi les entrées les plus pertinentes pour une requête AI donnée.

Domains : recherche refusée ou indisponible

Deux cas principaux :

• 429 — rate limit local de la recherche de domaine ;
• 5xx — provider domaine ou service temporairement indisponible.

Les limites actuelles sont 30 recherches client par 10 minutes et 45 recherches globales par minute dans le process inspecté.

Décider si un retry est sûr

Ne pas rejouer aveuglément une mutation

Après un timeout réseau, vous pouvez ignorer si le serveur a traité l’opération avant que la connexion soit perdue.

Soyez particulièrement prudent avec :

• création de projet ;
• création de memory ;
• checkpoint/version ;
• écritures Connector GitHub ;
• tout POST/PUT/PATCH/DELETE à effet persistant.

Connectors supporte un idempotencyKey dans son body, mais ce mécanisme n’est pas global à toute l’API.

Informations à collecter avant de signaler un bug

Ce qu’il ne faut jamais mettre dans un rapport

• cookie orbitwake_session ;
• token IDE ;
• pairing code encore valide ;
• secret webhook ;
• credential provider ;
• mot de passe ;
• clé privée ou contenu sensible d’un fichier.

Ce qui n’est pas encore standardisé

OrbitWake ne possède pas encore un système public unique de codes d’erreur machine, request IDs globaux, logs client téléchargeables ou commande universelle de diagnostic.

Cette page s’appuie donc sur les mécanismes réellement présents dans chaque surface au lieu d’inventer un outil de support central inexistant.

Prochaine ressource

La dernière entrée Ressources encore représentée par un placeholder est Changelog. Elle doit être construite à partir des changements réellement livrés, pas comme une liste marketing.