Errors

HTTP status codes, validation failures, and common error shapes returned by Africa API.

Status Codes You Should Handle

Status	Meaning	Typical Cause
`200`	Success	Request completed normally
`304`	Not Modified	`If-None-Match` matched the current countries list ETag
`400`	Bad Request	Invalid query combination such as `year` plus `start_year`
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Authenticated but not allowed to perform the action
`404`	Not Found	Missing country, indicator, geography, source, exchange, or ticker
`422`	Validation Error	Query parameter type or bounds are invalid
`429`	Too Many Requests	Per-minute rate limit or monthly request quota exceeded
`500`	Server Error	Unexpected backend failure

Common Error Shapes

400 / 404

{
  "detail": "indicator not found: median_income_usd"
}

401

{
  "detail": "missing bearer token"
}

422

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 1000",
      "type": "less_than_equal"
    }
  ]
}

Client Best Practices

Treat 304 as success and reuse the cached countries payload.
Retry transient per-minute 429 and 5xx responses with backoff. A monthly quota 429 needs a quota reset or a plan with more remaining capacity; see Rate limits.
Do not blindly retry 401, 403, 404, or 422.
Log the endpoint, status code, and detail payload.

Authentication

Bearer-token request format and protected routes.

Rate limits

Safe retry and batching guidance.

Status Codes You Should Handle

Common Error Shapes

400 / 404

401

422

Client Best Practices

Related

Authentication

Rate limits

On this page