API contract

Errors and rate limits

Every failure uses the same envelope. Branch on code, log request_id and retry only the conditions documented as transient.

Error envelope

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry in 12 seconds.",
    "request_id": "req_9f4c2b7a8d1e4f60"
  }
}

Code	HTTP	Action
missing_api_key	401	Add the Authorization header; do not retry unchanged.
invalid_api_key	401	Use the correct key or rotate it in the developer portal.
insufficient_scope	403	Request access to the product scope.
validation_failed	422	Correct the fields listed in error.details.
rate_limit_exceeded	429	Wait for Retry-After before retrying.
upstream_rate_limited	503	Back off; CAC throttled the NairaCheck upstream connection.
upstream_unavailable	503	Retry with exponential backoff and jitter.

Rate-limit headers

X-RateLimit-Limit — requests allowed per sliding minute.
X-RateLimit-Remaining — requests left in the current window.
X-RateLimit-Reset — seconds until capacity returns.
Retry-After — wait time included on a 429 response.