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
`500`	Server Error	Unexpected backend failure

Common Error Shapes

400 / 404

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

401

{
  "detail": "Not authenticated"
}

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 only 429 and 5xx responses.
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