# Errors All errors follow RFC 9457 (`application/problem+json`), with a stable, machine-readable `code` and the request identifier to quote to 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` leads to the description of the problem; `code` never changes; `errors[].pointer` is a JSON Pointer (RFC 6901); `allowed` repeats the closed list when there is one. - Messages in the request's `lang` when it exists (French in this example), otherwise in English. - A resource of another account or another mode answers `404`, like an unknown resource. - `401` carries `WWW-Authenticate`, `405` carries `Allow`, `429` carries `Retry-After`. - Exception: `/oauth/token` and `/oauth/revoke` answer in the RFC 6749 § 5.2 format (`error`, `error_description`). ## Code catalog | HTTP | Code | When | What to do | | 400 | `invalid_json` | Body that is not valid JSON. | Fix the body. | | 400 | `invalid_parameter` | Unknown or invalid parameter; language not available for the country (with the possible languages). | Fix the parameter. | | 413 | `payload_too_large` | Body larger than 16 KB. | Reduce the body (the free message is 2,000 characters at most). | | 415 | `unsupported_media_type` | `Content-Type` missing or other than `application/json` (`application/merge-patch+json` for `PATCH`). | Send the right header. | | 401 | `invalid_credentials` | Key or token missing, invalid or revoked; key passed in the address. | Check the key; do not retry in a loop. | | 401 | `expired_token` | OAuth token expired (15 minutes) or key replaced more than 24 hours ago. | Get a new token. | | 403 | `insufficient_scope` | Scope missing for this route. | Use a key or token with the required scope. | | 403 | `live_not_enabled` | Account not yet open in production. | Stay in the sandbox or ask for opening. | | 403 | `account_suspended` | Account suspended. | Write to Kelki. | | 403 | `country_not_available` | Country in preparation: catalog readable, requests refused. | Check `GET /countries`. | | 403 | `trade_not_available` | Trade not open to the API (health, under review, account exclusion). | Re-read `GET /trades`. | | 404 | `not_found` | Unknown resource, of another account or another mode; unknown version (`/v2`). | Check the identifier and the key. | | 409 | `invalid_state` | Impossible transition (updating a request already transmitted, confirming twice…). | Re-read the request, then decide. | | 409 | `idempotency_in_progress` | Request with the same `Idempotency-Key` still running. | Retry after a few seconds. | | 422 | `idempotency_key_reused` | Same `Idempotency-Key` with a different body. | New key for a new operation. | | 422 | `validation_failed` | Value refused by the form's rules (closed list, place, contact details). | Fix the field of `errors[].pointer`, offer `allowed`. | | 422 | `consent_missing` | Confirmation without `consent_given: true`. | Collect the person's consent. | | 422 | `consent_version_outdated` | Consent text version different from the draft's. | Display the draft's text and ask for consent again. | | 422 | `contact_limit_reached` | 3 requests in 24 hours for this phone or e-mail, all channels. | Invite the person to confirm the requests already received. | | 422 | `duplicate_request` | The same request is already pending for this person. | Re-read the existing request; no new e-mail is sent. | | 429 | `rate_limited` | Per-minute rate exceeded (key or IP address). | Wait for `Retry-After`. | | 429 | `quota_exceeded` | Daily quota reached (requests, real requests, agent messages). | Wait until the next day or ask for a higher plan. | | 500 | `internal_error` | Internal error (no details). | Retry; quote `request_id` to support if it persists. | | 503 | `agent_paused` | Kelki Agent paused. | Use `POST /requests`. | | 503 | `live_creation_paused` | Creation of real requests suspended for the account. | Write to Kelki. | | 503 | `service_unavailable` | Service temporarily unavailable or under maintenance. | Retry later ([status](https://kelki.ai/developers/en/status/)). | ## About this page - URL : https://kelki.ai/developers/en/errors/ - Language : en - fr : https://kelki.ai/developers/fr/errors/ - en : https://kelki.ai/developers/en/errors/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt