Erreurs
Toutes les erreurs suivent la RFC 9457 (application/problem+json), avec un code stable, lisible par une machine, et l'identifiant de la requête à citer au support.
Format
{
"type": "https://kelki.ai/api/problems/validation_failed",
"title": "Demande invalide",
"status": 422,
"detail": "Un champ ne respecte pas les règles du formulaire.",
"instance": "/api/v1/requests#rq_2c3d4e",
"code": "validation_failed",
"request_id": "rq_2c3d4e",
"errors": [{"pointer": "/service", "detail": "Prestation hors liste pour Plombier.",
"allowed": ["Recherche de fuite", "Réparation de fuite", "Débouchage", "Autre besoin"]}]
}
typemène à la description du problème ;codene change jamais ;errors[].pointerest un JSON Pointer (RFC 6901) ;allowedreprend la liste fermée quand il y en a une.- Messages dans la langue
langde la requête quand elle existe, sinon en anglais. - Une ressource d'un autre compte ou d'un autre mode répond
404, comme une ressource inconnue. 401porteWWW-Authenticate,405porteAllow,429porteRetry-After.- Exception :
/oauth/tokenet/oauth/revokerépondent au format de RFC 6749 § 5.2 (error,error_description).
Catalogue des codes
| HTTP | Code | Quand | Que faire |
|---|---|---|---|
| 400 | invalid_json | Corps qui n'est pas du JSON valide. | Corriger le corps. |
| 400 | invalid_parameter | Paramètre inconnu ou invalide ; langue non disponible pour le pays (avec les langues possibles). | Corriger le paramètre. |
| 413 | payload_too_large | Corps de plus de 16 Ko. | Réduire le corps (le message libre fait 2 000 caractères au plus). |
| 415 | unsupported_media_type | Content-Type absent ou autre que application/json (application/merge-patch+json pour PATCH). | Envoyer le bon en-tête. |
| 401 | invalid_credentials | Clé ou jeton absent, invalide ou révoqué ; clé passée dans l'adresse. | Vérifier la clé ; ne pas réessayer en boucle. |
| 401 | expired_token | Jeton OAuth expiré (15 minutes) ou clé remplacée depuis plus de 24 heures. | Demander un nouveau jeton. |
| 403 | insufficient_scope | Portée manquante pour cette route. | Utiliser une clé ou un jeton avec la portée requise. |
| 403 | live_not_enabled | Compte pas encore ouvert en production. | Rester en bac à sable ou demander l'ouverture. |
| 403 | account_suspended | Compte suspendu. | Écrire à Kelki. |
| 403 | country_not_available | Pays en préparation : référentiel lisible, demandes refusées. | Vérifier GET /countries. |
| 403 | trade_not_available | Métier non ouvert à l'API (santé, relecture, exclusion du compte). | Relire GET /trades. |
| 404 | not_found | Ressource inconnue, d'un autre compte ou d'un autre mode ; version inconnue (/v2). | Vérifier l'identifiant et la clé. |
| 409 | invalid_state | Transition impossible (modifier une demande déjà transmise, confirmer deux fois…). | Relire la demande puis décider. |
| 409 | idempotency_in_progress | Requête de même Idempotency-Key encore en cours. | Réessayer après quelques secondes. |
| 422 | idempotency_key_reused | Même Idempotency-Key avec un corps différent. | Nouvelle clé pour une nouvelle opération. |
| 422 | validation_failed | Valeur refusée par les règles du formulaire (liste fermée, lieu, coordonnées). | Corriger le champ de errors[].pointer, proposer allowed. |
| 422 | consent_missing | Confirmation sans consent_given: true. | Recueillir l'accord de la personne. |
| 422 | consent_version_outdated | Version du texte d'accord différente de celle du brouillon. | Afficher le texte du brouillon et redemander l'accord. |
| 422 | contact_limit_reached | 3 demandes en 24 heures pour ce téléphone ou cet e-mail, tous canaux. | Inviter la personne à confirmer les demandes déjà reçues. |
| 422 | duplicate_request | La même demande est déjà en attente pour cette personne. | Relire la demande existante ; aucun nouvel e-mail n'est envoyé. |
| 429 | rate_limited | Débit par minute dépassé (clé ou adresse IP). | Attendre Retry-After. |
| 429 | quota_exceeded | Quota du jour atteint (requêtes, demandes réelles, messages à l'agent). | Attendre le lendemain ou demander un plan supérieur. |
| 500 | internal_error | Erreur interne (sans détail). | Réessayer ; citer request_id au support si cela dure. |
| 503 | agent_paused | Agent Kelki en pause. | Passer par POST /requests. |
| 503 | live_creation_paused | Création de demandes réelles suspendue pour le compte. | Écrire à Kelki. |
| 503 | service_unavailable | Service momentanément indisponible ou en maintenance. | Réessayer plus tard (statut). |