# 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"]}] } ``` - `type` mène à la description du problème ; `code` ne change jamais ; `errors[].pointer` est un JSON Pointer (RFC 6901) ; `allowed` reprend la liste fermée quand il y en a une. - Messages dans la langue `lang` de 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. - `401` porte `WWW-Authenticate`, `405` porte `Allow`, `429` porte `Retry-After`. - Exception : `/oauth/token` et `/oauth/revoke` ré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](https://kelki.ai/developers/fr/status/)). | ## Sur cette page - URL : https://kelki.ai/developers/fr/errors/ - Langue : fr - fr : https://kelki.ai/developers/fr/errors/ - en : https://kelki.ai/developers/en/errors/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt