Error Codes

These HTTP / response_code values apply to all Peleza API calls, not a single endpoint. Use status together with message and request_id when handling errors.

Response envelope

Typical shape:

Sample dataEnvelope

{
  "success": false,
  "response_code": 400,
  "message": "Human-readable status message",
  "errors": {
    "field_name": "Validation message for this field"
  },
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

success — whether the call succeeded
response_code — application code (usually mirrors HTTP)
message — human-readable status
errors — optional field-level validation map (400)
data — payload on success; usually null on error
request_id — UUID for support and audit (always log this)
country — present on country-scoped routes (e.g. /id/ke)

Status codes (all APIs)

Expected codes for every Peleza API request. Validation field names and message text vary by endpoint; the codes and billing rules do not.

HTTP / response_code	When	Billed?
200	Request succeeded — details returned	Yes*
400	Validation — missing or invalid request fields	No
401	Missing or invalid Bearer token	No
402	Insufficient wallet balance or credit limit	No
403	No active wallet or billing profile (or service not enabled)	No
404	Resource not found after verification completed — or unsupported country	Yes (found path completed) / No (unsupported country)
408	Upstream timeout / service error	No
429	Rate limited	No
502	Upstream bad or unreadable response	No
503	Upstream connection unavailable	No

* 200 is billed only on paid verification / lookup routes (e.g. National ID). Free routes such as OAuth token, token validate, and wallet balance are not billed on success.

OAuth / authentication errors

HTTP	When
400	Invalid JSON body, or missing grant_type / client_id / client_secret
401	Invalid client credentials on /oauth/token, or expired/invalid Bearer on protected routes

Token lifetime is TOKEN_TTL_SECONDS (currently 360 seconds). On 401 from a protected route, request a new token from POST /api/v1/oauth/token.

Billing behaviour

Debit runs after the response for HTTP 2xx and 404 when the verification path completed (aligned with Merchant wallet middleware).
Validation 400 and auth/wallet 401 / 402 / 403 are not billed.
Upstream 408 / 502 / 503 and rate limit 429 are not billed.
Unsupported-country 404 is not billed.
KES wallets on VAT-enabled tenants may include VAT in the debit total; non-KES currencies skip VAT.

Sample error payloads

Illustrative payloads (field names / messages differ by endpoint):

400 — validation

400Sample data400 Validation

{
  "success": false,
  "response_code": 400,
  "message": "The scope field is required",
  "country": "ke",
  "errors": {
    "scope": "The scope field is required"
  },
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440010"
}

401 — unauthorized

401Sample data401 Unauthorized

{
  "success": false,
  "response_code": 401,
  "message": "Unauthorized. Please provide a valid access token.",
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440011"
}

402 — insufficient funds

402Sample data402 Payment required

{
  "success": false,
  "response_code": 402,
  "message": "Insufficient wallet balance. Please top up.",
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440012"
}

404 — not found

404Sample data404 Not found

{
  "success": false,
  "response_code": 404,
  "message": "Kenya ID not found",
  "description": "There is no information for requested search parameters",
  "country": "ke",
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440013"
}

408 — upstream timeout

408Sample data408 Timeout

{
  "success": false,
  "response_code": 408,
  "message": "Verification service temporarily unavailable",
  "country": "ke",
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440014"
}