Aller au contenu
KelkiDéveloppeurs

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"]}]
}

Catalogue des codes

HTTPCodeQuandQue faire
400invalid_jsonCorps qui n'est pas du JSON valide.Corriger le corps.
400invalid_parameterParamètre inconnu ou invalide ; langue non disponible pour le pays (avec les langues possibles).Corriger le paramètre.
413payload_too_largeCorps de plus de 16 Ko.Réduire le corps (le message libre fait 2 000 caractères au plus).
415unsupported_media_typeContent-Type absent ou autre que application/json (application/merge-patch+json pour PATCH).Envoyer le bon en-tête.
401invalid_credentialsClé ou jeton absent, invalide ou révoqué ; clé passée dans l'adresse.Vérifier la clé ; ne pas réessayer en boucle.
401expired_tokenJeton OAuth expiré (15 minutes) ou clé remplacée depuis plus de 24 heures.Demander un nouveau jeton.
403insufficient_scopePortée manquante pour cette route.Utiliser une clé ou un jeton avec la portée requise.
403live_not_enabledCompte pas encore ouvert en production.Rester en bac à sable ou demander l'ouverture.
403account_suspendedCompte suspendu.Écrire à Kelki.
403country_not_availablePays en préparation : référentiel lisible, demandes refusées.Vérifier GET /countries.
403trade_not_availableMétier non ouvert à l'API (santé, relecture, exclusion du compte).Relire GET /trades.
404not_foundRessource inconnue, d'un autre compte ou d'un autre mode ; version inconnue (/v2).Vérifier l'identifiant et la clé.
409invalid_stateTransition impossible (modifier une demande déjà transmise, confirmer deux fois…).Relire la demande puis décider.
409idempotency_in_progressRequête de même Idempotency-Key encore en cours.Réessayer après quelques secondes.
422idempotency_key_reusedMême Idempotency-Key avec un corps différent.Nouvelle clé pour une nouvelle opération.
422validation_failedValeur refusée par les règles du formulaire (liste fermée, lieu, coordonnées).Corriger le champ de errors[].pointer, proposer allowed.
422contact_limit_reached3 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.
422duplicate_requestLa même demande est déjà en attente pour cette personne.Relire la demande existante ; aucun nouvel e-mail n'est envoyé.
429rate_limitedDébit par minute dépassé (clé ou adresse IP).Attendre Retry-After.
429quota_exceededQuota du jour atteint (requêtes, demandes réelles, messages à l'agent).Attendre le lendemain ou demander un plan supérieur.
500internal_errorErreur interne (sans détail).Réessayer ; citer request_id au support si cela dure.
503agent_pausedAgent Kelki en pause.Passer par POST /requests.
503live_creation_pausedCréation de demandes réelles suspendue pour le compte.Écrire à Kelki.
503service_unavailableService momentanément indisponible ou en maintenance.Réessayer plus tard (statut).