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"]}]
}
typeleads to the description of the problem;codenever changes;errors[].pointeris a JSON Pointer (RFC 6901);allowedrepeats the closed list when there is one.- Messages in the request's
langwhen it exists (French in this example), otherwise in English. - A resource of another account or another mode answers
404, like an unknown resource. 401carriesWWW-Authenticate,405carriesAllow,429carriesRetry-After.- Exception:
/oauth/tokenand/oauth/revokeanswer 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). |