Webhooks, Erreurs & Pagination

Format des réponses d'erreur

Toutes les erreurs API suivent un format JSON cohérent. Le statusCode correspond au statut HTTP, message fournit une explication lisible, et error contient le texte standard du statut HTTP.

{
  "statusCode": 422,
  "message": "Validation échouée : le SKU doit être unique au sein du tenant",
  "error": "Unprocessable Entity"
}

Erreurs de validation

Lorsqu'un corps de requête échoue à la validation, la réponse inclut un tableau d'erreurs spécifiques par champ :

{
  "statusCode": 400,
  "message": [
    "name doit être une chaîne de caractères",
    "price doit être un nombre positif",
    "sku ne doit pas être vide"
  ],
  "error": "Bad Request"
}

Codes de statut HTTP

L'API utilise les codes de statut HTTP standards pour indiquer le résultat de chaque requête :

Codes de succès

• 200 OK — Requête réussie. Le corps de la réponse contient les données demandées.
• 201 Created — Ressource créée avec succès. Le corps de la réponse contient la nouvelle ressource.
• 204 No Content — Requête réussie sans corps de réponse (par ex. après DELETE).

Codes d'erreur client

• 400 Bad Request — Corps de requête ou paramètres invalides. Vérifiez les erreurs de validation dans la réponse.
• 401 Unauthorized — Jeton d'authentification manquant ou expiré. Rafraîchissez votre jeton et réessayez.
• 403 Forbidden — Authentifié mais sans permission pour cette ressource ou action.
• 404 Not Found — La ressource demandée n'existe pas ou appartient à un autre tenant.
• 409 Conflict — Ressource en double. Par exemple, un produit avec le même SKU existe déjà.
• 422 Unprocessable Entity — Syntaxe valide mais sémantiquement incorrecte. Par exemple, une transition de statut invalide sur une commande.
• 429 Too Many Requests — Limite de débit dépassée. Attendez et réessayez avec un backoff exponentiel.

Codes d'erreur serveur

• 500 Internal Server Error — Une erreur inattendue s'est produite. Si elle persiste, contactez le support avec les détails de la requête.

Limitation de débit

L'API applique des limites de débit pour assurer une utilisation équitable et la stabilité de la plateforme :

• Endpoints généraux : 100 requêtes par minute par jeton API.
• Endpoints d'authentification : 5 requêtes par minute par adresse IP.
• Déclencheurs de synchronisation : 10 requêtes par minute par canal.

Les en-têtes de limite de débit sont inclus dans chaque réponse :

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710500460

Pagination

Tous les endpoints de liste retournent des résultats paginés avec un objet meta cohérent :

{
  "data": [ ... ],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

Paramètres de pagination

• page — Le numéro de page à récupérer (par défaut : 1, minimum : 1).
• limit — Le nombre d'éléments par page (par défaut : 20, minimum : 1, maximum : 100).

Webhooks

Kataio peut envoyer des notifications HTTP POST à vos endpoints lorsque des événements clés se produisent. Les charges utiles des webhooks sont en JSON et incluent un type d'événement, un horodatage et les données de la ressource concernée.

Format de charge utile webhook

{
  "event": "product.updated",
  "timestamp": "2026-03-15T09:12:00.000Z",
  "data": {
    "id": "prod_01H8X...",
    "name": "Chemise Oxford Bleue",
    "sku": "CHM-OXF-BLU-001",
    "status": "ACTIVE",
    "updatedFields": ["price", "compareAtPrice"]
  }
}

Événements disponibles

• product.created / product.updated / product.deleted
• order.created / order.status_changed
• inventory.low_stock / inventory.movement_created
• channel.sync_completed / channel.sync_failed
• bulk.import_completed / bulk.import_failed
• sync.push_completed / sync.push_failed
• sync.cancelled

Politique de réessai

Si votre endpoint ne répond pas avec un statut 2xx dans les 10 secondes, Kataio réessaie jusqu'à 3 fois avec un backoff exponentiel (30 secondes, 2 minutes, 10 minutes). Après l'échec de tous les réessais, le webhook est marqué comme échoué et apparaît dans les journaux de webhooks.