Errors

Status Codes You Should Handle

Status	Meaning	Typical Cause
`200`	Success	Request completed normally
`304`	Not Modified	`If-None-Match` matched current ETag
`400`	Bad Request	Invalid query parameter (example: unsupported sort field)
`404`	Not Found	Country code does not exist
`422`	Validation Error	Invalid parameter type/range
`500`	Server Error	Unexpected backend failure

Error Shapes

400 / 404

{
  "detail": "country not found: xx"
}

422

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

Client Best Practices

Treat 304 as success and use cached data.
Retry 5xx with jittered backoff.
Do not retry 4xx blindly.
Log detail and request id context for debugging.

Errors

Status Codes You Should Handle

Error Shapes

400 / 404

422

Client Best Practices

On this page