Codes d'erreur

En bref

Toutes les reponses API suivent une enveloppe standard. En cas d'erreur, le champ error contient un code machine, un message lisible, un indicateur de retry et une remediation suggeree.

Format d'erreur

{
  "ok": false,
  "data": null,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "API key missing required scope: writes",
    "retryable": false,
    "remediation": "Add the 'writes' scope to your API key in Settings > API Keys.",
    "details": { "requiredScope": "writes", "presentScopes": ["reads"] }
  },
  "meta": { "requestId": "req_abc123", "timestamp": "2026-05-16T10:00:00Z" }
}

Familles d'erreurs

Validation (HTTP 400)

Code	Description	Remediation
INVALID_INPUT	Corps de requete invalide	Verifiez le format des champs
MISSING_FIELD	Champ requis manquant	Ajoutez le champ indique dans details
TYPE_MISMATCH	Type de donnee incorrect	Corrigez le type (string, number, etc.)

Authentification (HTTP 401)

Code	Description	Remediation
AUTH_FAILED	Authentification echouee	Verifiez votre cle API ou token
TOKEN_EXPIRED	Token OAuth expire	Rafraichissez via le refresh token
KEY_INVALID	Cle API invalide ou revoquee	Generez une nouvelle cle dans Settings

Autorisation (HTTP 403)

Code	Description	Remediation
SCOPE_DENIED	Scope manquant sur la cle API	Ajoutez le scope requis
WRITE_POLICY_VIOLATION	Politique d'ecriture non respectee	Verifiez les regles de gouvernance
RBAC_DENIED	Role insuffisant	Contactez votre administrateur

Drift et conflits (HTTP 409)

Code	Description	Remediation
PLAN_SCHEMA_MISMATCH	Schema modifie depuis le dry-run	Refaites un dry-run
PLAN_POLICY_MISMATCH	Politique modifiee depuis le dry-run	Refaites un dry-run
PLAN_ACTION_MISMATCH	Definition d'action modifiee	Refaites un dry-run
SCHEMA_DRIFT	Schema local diverge du serveur	Executez ontologie schema pull
OCC_CONFLICT	Conflit de version optimiste	Relisez l'entite et renvoyez avec la bonne version

Plans (HTTP 409-412)

Code	Description	Remediation
PLAN_NOT_FOUND	Plan introuvable	Verifiez le planId
PLAN_EXPIRED	Plan expire	Refaites un dry-run
PLAN_REVOKED	Plan revoque	Refaites un dry-run
PLAN_ALREADY_APPLIED	Plan deja execute	Aucune action (idempotent)
PLAN_ACTOR_MISMATCH	Principal different du createur	Utilisez le meme principal
PLAN_SIGNATURE_INVALID	Signature invalide	Refaites un dry-run
PLAN_TARGET_VERSION_CONFLICT	Version cible changee	Relisez l'entite, refaites un dry-run
ACTION_PRECONDITION_FAILED	Precondition non satisfaite	Verifiez l'etat actuel de l'entite
CONFIRMATION_REQUIRED	Confirmation manquante	Ajoutez confirmed: true et riskAcknowledged: true

Rate limiting et quotas (HTTP 429)

Code	Description	Remediation
RATE_LIMITED	Trop de requetes	Attendez Retry-After secondes
BUDGET_EXCEEDED	Budget DFU depasse	Augmentez votre budget ou achetez des DFU
COMMAND_COST_LIMIT_EXCEEDED	Commande trop couteuse	Reduisez la complexite ou augmentez la limite
QUOTA_EXCEEDED	Quota du plan atteint	Passez au plan superieur

Balance (HTTP 402)

Code	Description	Remediation
DFU_BALANCE_INSUFFICIENT	Solde DFU insuffisant	Rechargez via le dashboard ou activez l'auto-recharge

Reseau (HTTP 504)

Code	Description	Remediation
TIMEOUT_ERROR	Timeout de la requete	Retentez apres un delai
NETWORK_ERROR	Erreur reseau	Verifiez la connectivite

Gestion dans le SDK

import { createClient, OntologieError } from '@ontologie/sdk-client';

try {
  await client.actions.apply(planId, { confirmed: true, riskAcknowledged: true });
} catch (error) {
  if (error instanceof OntologieError) {
    if (error.retryable) {
      // Attendre et retenter
      await sleep(error.retryAfter ?? 1000);
      // ... retry
    } else {
      console.error(`[${error.code}] ${error.message}`);
      console.error('Remediation:', error.remediation);
    }
  }
}

Codes de sortie CLI

Exit	Famille
0	Succes
1	Erreur interne
2	Validation
3	Authentification
4	Autorisation
5	Drift
7	Conflit
8	Rate limit
9	Reseau
10	Precondition
11	Quota
12	Configuration

Voir aussi

• SDK TypeScript — Vue d'ensemble
• Plans et Actions — Cycle de vie des mutations
• Facturation et limites — Quotas et DFU
• Depannage — Guide de resolution