Reference

Errors

Every error returns a structured JSON body with a stable code, a human message, and a request_id for support.

Shape#

json

{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "request_id": "req_01HX7K2A3B4C5D",
  "details": [
    { "field": "member.date_of_birth", "message": "Must be a valid ISO 8601 date" }
  ]
}

Common codes#

Code	Status	Meaning
VALIDATION_ERROR	422	Request body failed schema validation
AUTHENTICATION_FAILED	401	Missing or invalid credentials
PERMISSION_DENIED	403	Authenticated but not permitted
RESOURCE_NOT_FOUND	404	Resource does not exist or is filtered by tenant
IDENTITY_MISMATCH	422	NIN/BVN data did not match enrollment
IDEMPOTENCY_CONFLICT	409	Idempotency key used with a different body
RATE_LIMITED	429	Tier limit exceeded; honour Retry-After
UPSTREAM_UNAVAILABLE	502	HMO or payment gateway is unreachable

When you need help#

Always quote the request_id when filing a support ticket. It lets us replay the exact call without you re-sending the body.