Erreurs & Pagination

Gérez correctement les réponses API pour des intégrations robustes.

Format des erreurs

Toutes les erreurs suivent une structure JSON cohérente :

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Type d'entité invalide",
    "details": {
      "field": "entityType",
      "allowed": ["concept", "object", "process", "actor"]
    }
  },
  "requestId": "req_xxxxxxxxxxxx"
}

Codes HTTP

Codes de succès

Code	Signification	Utilisation
200	OK	GET/PUT/PATCH réussi
201	Created	POST réussi (ressource créée)
204	No Content	DELETE réussi

Erreurs client

Code	Signification	Cause courante
400	Bad Request	JSON invalide, champs requis manquants
401	Unauthorized	Clé API invalide/manquante
403	Forbidden	Permissions insuffisantes, mauvais workspace
404	Not Found	Ressource inexistante
409	Conflict	Conflit de version (édition concurrente)
422	Unprocessable	Validation échouée (JSON valide, données invalides)
429	Too Many Requests	Rate limit dépassé

Erreurs serveur

Code	Signification	Action
500	Internal Server Error	Réessayer avec backoff, signaler si persistant
502	Bad Gateway	Problème temporaire, réessayer
503	Service Unavailable	Maintenance, consulter la page de status
504	Gateway Timeout	Requête trop lente, réessayer

Codes d'erreur

Code	Description
VALIDATION_ERROR	Validation du payload échouée
AUTHENTICATION_ERROR	Credentials invalides ou manquants
AUTHORIZATION_ERROR	Permissions insuffisantes
NOT_FOUND	Ressource demandée introuvable
CONFLICT	Conflit de ressource (doublon, version incorrecte)
RATE_LIMITED	Trop de requêtes
INTERNAL_ERROR	Erreur côté serveur

Rate Limiting

Headers de rate limit

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 23
X-RateLimit-Reset: 1700000000
Retry-After: 45

Gestion du rate limit

async function apiCall(url, options, retries = 3) {
  const response = await fetch(url, options);

  if (response.status === 429 && retries > 0) {
    const retryAfter = response.headers.get('Retry-After') || 60;
    await sleep(retryAfter * 1000);
    return apiCall(url, options, retries - 1);
  }

  return response;
}

Backoff exponentiel

const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
await sleep(delay + Math.random() * 1000); // Ajouter du jitter

Pagination

Paramètres de requête

Paramètre	Type	Défaut	Max	Description
limit	integer	50	100	Éléments par page
offset	integer	0	-	Éléments à sauter

Exemple de requête

curl "https://api.dev-growthsystemes.com/api/queries/nodes?limit=20&offset=40" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

Métadonnées de réponse

{
  "success": true,
  "data": [...],
  "meta": {
    "total": 156,
    "limit": 20,
    "offset": 40,
    "hasMore": true
  }
}

Parcourir toutes les pages

async function fetchAll(endpoint) {
  const results = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch(
      `${endpoint}?limit=${limit}&offset=${offset}`,
      { headers }
    );
    const { data, meta } = await response.json();

    results.push(...data);

    if (!meta.hasMore) break;
    offset += limit;
  }

  return results;
}

Filtrage & Tri

Paramètres de filtrage

# Filtrer par type d'entité
?entityType=concept

# Filtrer par nom (correspondance partielle)
?name=Client

# Filtres multiples (logique ET)
?entityType=concept&name=Client

Paramètres de tri

# Tri ascendant
?sort=name

# Tri descendant
?sort=-createdAt

# Champs de tri multiples
?sort=-updatedAt,name

Gestion des conflits de version

Version attendue

Prévenir les conflits de modification concurrente :

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": "xxx", "name": "Nouveau Nom" },
    "expectedVersion": 5
  }'

Gestion du 409 Conflict

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

Résolution : Recharger la ressource, fusionner les changements, réessayer avec la nouvelle version.

Suivi des requêtes

Chaque réponse inclut un requestId pour le débogage :

{
  "requestId": "req_abc123def456"
}

Incluez-le dans vos tickets de support pour une résolution plus rapide.