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.
{
"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
