Erreurs courantes

Guide de dépannage pour les problèmes courants avec l'API DataForge.

Erreurs d'authentification

401 Unauthorized

Symptômes :

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

Causes possibles :

• Header Authorization manquant
• Format de clé API invalide
• Clé API expirée
• Clé API révoquée

Solutions :

# Vérifier le format du header (doit inclure "Bearer ")
curl -H "Authorization: Bearer df_live_xxx"  # Correct
curl -H "Authorization: df_live_xxx"         # Incorrect

# Vérifier que la clé est valide dans Paramètres > Clés API

403 Forbidden

Symptômes :

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

Causes possibles :

• Scope requis manquant
• Mauvais ID de workspace
• Clé non autorisée pour ce workspace

Solutions :

# Vérifier le header workspace
curl -H "x-workspace-id: $WORKSPACE_ID"

# Vérifier les scopes de la clé dans Paramètres > Clés API
# Scopes requis :
# - read:nodes pour GET /api/queries/nodes
# - write:nodes pour POST /api/commands/execute

Erreurs de requête

400 Bad Request

Symptômes :

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

Solutions :

• Vérifier la syntaxe JSON
• Vérifier les champs requis
• Vérifier les types de champs (string vs number)
• Valider le format des UUIDs

# Valider le JSON avant envoi
echo '{"name":"test"}' | jq .

# Vérifier 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

Causes possibles :

• Ressource supprimée
• Mauvais ID de ressource
• Mauvaise URL d'endpoint
• Ressource dans un autre workspace

Solutions :

# Vérifier que l'endpoint existe
curl "https://api.dev-growthsystemes.com/api/queries/nodes"  # Correct
curl "https://api.dev-growthsystemes.com/api/node"           # Incorrect

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

409 Conflict

Symptômes :

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

Cause : Conflit de version - une autre requête a modifié la ressource.

Solution :

1. Recharger la ressource pour obtenir la dernière version
2. Fusionner vos changements
3. Réessayer avec la nouvelle expectedVersion

# 1. Obtenir la version actuelle
VERSION=$(curl -s "https://api.dev-growthsystemes.com/api/queries/nodes/$ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" | jq '.data.version')

# 2. Mettre à jour avec la bonne version
curl -X POST "https://api.dev-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

Symptômes :

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

Cause : JSON valide mais données invalides.

Solutions :

• Vérifier les valeurs autorisées pour chaque champ
• Consulter la documentation de l'endpoint

429 Too Many Requests

Symptômes :

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

Solutions :

// Implémenter 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 dépassé');
}

Erreurs serveur

500 Internal Server Error

Actions :

1. Réessayer la requête après 5 secondes
2. Vérifier 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": "/api/commands/execute",
  "payload": "..."
}

503 Service Unavailable

Causes possibles :

• Maintenance planifiée
• Surcharge système
• Déploiement en cours

Actions :

1. Vérifier la page de status
2. Réessayer avec backoff exponentiel
3. Attendre 5-10 minutes

Erreurs spécifiques aux fonctionnalités

Modeler : Entité non visible

Cause : Délai de synchronisation.

Solution : Attendre 100ms puis rafraîchir la page.

Modeler : Création de relation échoue

Cause : IDs source ou target invalides.

Solution : Vérifier que les deux entités existent dans le workspace.

Live Data : Source non connectée

Causes possibles :

• URL incorrecte
• Credentials invalides
• Firewall bloquant la connexion

Solution : Utiliser l'endpoint de test de connexion :

curl -X POST "https://api.dev-growthsystemes.com/api/live-data/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 prêt

Symptômes :

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

Solution : Attendre la fin de l'indexation ou déclencher manuellement :

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

API Keys : Scope insuffisant

Symptômes :

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

Solution : Créer une nouvelle clé avec les scopes requis ou modifier la clé existante.

Checklist de débogage

Étape 1 : Vérifier la connexion

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

Étape 2 : Vérifier l'authentification

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

Étape 3 : Vérifier le format de requête

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

# Tester avec un payload minimal
curl -X POST "https://api.dev-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}}}'

Étape 4 : Comparer avec la documentation

• Consulter la Référence API pour le bon endpoint
• Vérifier les champs requis
• Vérifier les types de données

Étape 5 : Activer le mode verbose

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

Vérifier :

• Headers de réponse
• Code HTTP
• Corps de la réponse

Obtenir de l'aide

Informations à inclure

1. Request ID - Depuis la réponse d'erreur
2. Timestamp - Quand l'erreur s'est produite
3. Endpoint - URL complète appelée
4. Corps de la requête - Sanitisé (sans secrets)
5. Réponse - Message d'erreur complet
6. Étapes pour reproduire

Canaux de support

• GitHub Issues: github.com/growthsystemes/dataforge/issues
• Email: support@growthsystemes.com
• Page de status: status.dev-growthsystemes.com