Aller au contenu
ONTOLOGIE
FRENCommunautéPlanifier une démo

Référence

Erreurs courantes

Guide de depannage pour les erreurs courantes de l'API Ontologie

3 min

En bref

Ce guide de reference repertorie les erreurs les plus frequentes de l'API Ontologie, avec leurs causes et solutions.

Prerequis techniques

  • Une cle API active avec les scopes necessaires.
  • Un acces a un workspace Ontologie.
  • Un client HTTP (curl, Postman, Insomnia ou equivalent).

Erreurs d'authentification {#auth-errors}

401 Unauthorized {#401}

Symptomes :

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

Causes possibles :

  • Header Authorization manquant
  • Format de cle API invalide
  • Cle API expiree
  • Cle API revoquee

Solutions :

# Verifier le format du header (doit inclure "Bearer ")
curl -H "Authorization: Bearer df_xxx"  # Correct
curl -H "Authorization: df_xxx"         # Incorrect

# Verifier que la cle est valide dans Parametres > Cles API

403 Forbidden {#403}

Symptomes :

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Insufficient permissions"
  }
}

Causes possibles :

  • Scope requis manquant
  • Mauvais ID de workspace
  • Cle non autorisee pour ce workspace

Solutions :

# Verifier le header workspace
curl -H "x-workspace-id: $WORKSPACE_ID"

# Verifier les scopes de la cle dans Parametres > Cles API
# Scopes requis :
# - read:nodes pour GET /reference/api/queries/nodes
# - write:nodes pour POST /reference/api/commands/execute

Erreurs de requete {#request-errors}

400 Bad Request {#400}

Symptomes :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { "field": "entityType", "issue": "required" }
  }
}

Solutions :

  • Verifier la syntaxe JSON
  • Verifier les champs requis
  • Verifier les types de champs (string vs number)
  • Valider le format des UUIDs
# Valider le JSON avant envoi
echo '{"name":"test"}' | jq .

# Verifier le format UUID
echo $ID | grep -E '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'

404 Not Found {#404}

Causes possibles :

  • Ressource supprimee
  • Mauvais ID de ressource
  • Mauvaise URL d'endpoint
  • Ressource dans un autre workspace

Solutions :

# Verifier que l'endpoint existe
curl "https://api.ontologie-growthsystemes.com/api/queries/nodes"  # Correct
curl "https://api.ontologie-growthsystemes.com/api/node"           # Incorrect

# Verifier que la ressource existe
curl "https://api.ontologie-growthsystemes.com/api/queries/nodes/$ENTITY_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

409 Conflict {#409}

Symptomes :

{
  "error": {
    "code": "CONFLICT",
    "message": "Version mismatch",
    "details": {
      "expectedVersion": 5,
      "actualVersion": 7
    }
  }
}

Cause : Conflit de version : une autre requete a modifie la ressource.

Solution :

  1. Recharger la ressource pour obtenir la derniere version
  2. Fusionner vos changements
  3. Reessayer avec la nouvelle expectedVersion
# 1. Obtenir la version actuelle
VERSION=$(curl -s "https://api.ontologie-growthsystemes.com/api/queries/nodes/$ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" | jq '.data.version')

# 2. Mettre a jour avec la bonne version
curl -X POST "https://api.ontologie-growthsystemes.com/api/commands/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"UPDATE_NODE\",
    \"payload\": { \"id\": \"$ID\", \"name\": \"Nouveau Nom\" },
    \"expectedVersion\": $VERSION
  }"

422 Unprocessable Entity {#422}

Symptomes :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "entityType": "must be one of: concept, object, process, actor"
    }
  }
}

Cause : JSON valide mais donnees invalides.

Solutions :

  • Verifier les valeurs autorisees pour chaque champ
  • Consulter la documentation de l'endpoint

429 Too Many Requests {#429}

Symptomes :

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Remaining: 0

Solutions :

// Implementer un backoff exponentiel
async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Nombre maximum de tentatives depasse');
}

Erreurs serveur {#server-errors}

500 Internal Server Error {#500}

Actions :

  1. Reessayer la requete apres 5 secondes
  2. Verifier la page de status
  3. Si persistant, signaler avec le requestId
# Inclure le requestId dans le ticket de support
{
  "requestId": "req_abc123def456",
  "timestamp": "2024-01-15T10:30:00Z",
  "endpoint": "/reference/api/commands/execute",
  "payload": "..."
}

503 Service Unavailable {#503}

Causes possibles :

  • Maintenance planifiee
  • Surcharge systeme
  • Deploiement en cours

Actions :

  1. Verifier la page de status
  2. Reessayer avec backoff exponentiel
  3. Attendre 5-10 minutes

Erreurs specifiques aux fonctionnalites {#feature-errors}

Modeler : Entite non visible {#modeler-entity-invisible}

Cause : Delai de synchronisation.

Solution : Attendre 100ms puis rafraichir la page.

Modeler : Creation de relation echoue {#modeler-edge-fail}

Cause : IDs source ou target invalides.

Solution : Verifier que les deux entites existent dans le workspace.

Live Data : Source non connectee {#livedata-not-connected}

Causes possibles :

  • URL incorrecte
  • Credentials invalides
  • Firewall bloquant la connexion

Solution : Utiliser l'endpoint de test de connexion :

curl -X POST "https://api.ontologie-growthsystemes.com/api/connecter/donnees/test-connection" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "rest",
    "config": {
      "url": "https://api.example.com/data"
    }
  }'

RAG : Index non pret {#rag-index-not-ready}

Symptomes :

{
  "error": {
    "code": "INDEX_NOT_READY",
    "message": "Vector index is still building"
  }
}

Solution : Attendre la fin de l'indexation ou declencher manuellement :

# Verifier le status
curl "https://api.ontologie-growthsystemes.com/api/rag/index/status" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

API Keys : Scope insuffisant {#api-keys-scope}

Symptomes :

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "API key does not have required scope: write:nodes"
  }
}

Solution : Creer une nouvelle cle avec les scopes requis ou modifier la cle existante.

Checklist de debogage {#checklist}

Etape 1 : Verifier la connexion {#step1}

curl -s "https://api.ontologie-growthsystemes.com/api/queries/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

Etape 2 : Verifier l'authentification {#step2}

# Verifier les headers
curl -v "https://api.ontologie-growthsystemes.com/api/queries/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" 2>&1 | head -50

Etape 3 : Verifier le format de requete {#step3}

# Valider le JSON
echo "$REQUEST_BODY" | jq .

# Tester avec un payload minimal
curl -X POST "https://api.ontologie-growthsystemes.com/api/commands/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"type":"CREATE_NODE","payload":{"name":"Test","entityType":"concept","position":{"x":0,"y":0}}}'

Etape 4 : Comparer avec la documentation {#step4}

  • Consulter la référence API pour le bon endpoint
  • Verifier les champs requis
  • Verifier les types de donnees

Etape 5 : Activer le mode verbose {#step5}

curl -v "https://api.ontologie-growthsystemes.com/api/queries/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

Verifier :

  • Headers de reponse
  • Code HTTP
  • Corps de la reponse

Obtenir de l'aide {#help}

Informations a inclure {#info}

  1. Request ID : Depuis la reponse d'erreur
  2. Timestamp : Quand l'erreur s'est produite
  3. Endpoint : URL complete appelee
  4. Corps de la requete : Sanitise (sans secrets)
  5. Reponse : Message d'erreur complet
  6. Etapes pour reproduire

Canaux de support {#channels}

Besoin d'aide ?

Ecrivez-nous : Support et contact.