Skip to content
KelkiDevelopers

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

Code catalog

HTTPCodeWhenWhat to do
400invalid_jsonBody that is not valid JSON.Fix the body.
400invalid_parameterUnknown or invalid parameter; language not available for the country (with the possible languages).Fix the parameter.
413payload_too_largeBody larger than 16 KB.Reduce the body (the free message is 2,000 characters at most).
415unsupported_media_typeContent-Type missing or other than application/json (application/merge-patch+json for PATCH).Send the right header.
401invalid_credentialsKey or token missing, invalid or revoked; key passed in the address.Check the key; do not retry in a loop.
401expired_tokenOAuth token expired (15 minutes) or key replaced more than 24 hours ago.Get a new token.
403insufficient_scopeScope missing for this route.Use a key or token with the required scope.
403live_not_enabledAccount not yet open in production.Stay in the sandbox or ask for opening.
403account_suspendedAccount suspended.Write to Kelki.
403country_not_availableCountry in preparation: catalog readable, requests refused.Check GET /countries.
403trade_not_availableTrade not open to the API (health, under review, account exclusion).Re-read GET /trades.
404not_foundUnknown resource, of another account or another mode; unknown version (/v2).Check the identifier and the key.
409invalid_stateImpossible transition (updating a request already transmitted, confirming twice…).Re-read the request, then decide.
409idempotency_in_progressRequest with the same Idempotency-Key still running.Retry after a few seconds.
422idempotency_key_reusedSame Idempotency-Key with a different body.New key for a new operation.
422validation_failedValue refused by the form's rules (closed list, place, contact details).Fix the field of errors[].pointer, offer allowed.
422contact_limit_reached3 requests in 24 hours for this phone or e-mail, all channels.Invite the person to confirm the requests already received.
422duplicate_requestThe same request is already pending for this person.Re-read the existing request; no new e-mail is sent.
429rate_limitedPer-minute rate exceeded (key or IP address).Wait for Retry-After.
429quota_exceededDaily quota reached (requests, real requests, agent messages).Wait until the next day or ask for a higher plan.
500internal_errorInternal error (no details).Retry; quote request_id to support if it persists.
503agent_pausedKelki Agent paused.Use POST /requests.
503live_creation_pausedCreation of real requests suspended for the account.Write to Kelki.
503service_unavailableService temporarily unavailable or under maintenance.Retry later (status).