Errors

When something goes wrong, the API returns a consistent error format along with an appropriate HTTP status code.

Error format#

jsonc

{
	"error": "not_found",
	"message": "No country found for identifier 'XYZ'",
}

The error field is a machine-readable code your application can match against. The message field is a human-readable explanation — useful for debugging, but don't parse it programmatically since the wording may change.

Status codes#

Status	Meaning
`400`	Bad request — malformed syntax, missing required parameter
`401`	Unauthorized — invalid or missing API key for a protected endpoint
`403`	Forbidden — valid key, but insufficient permissions (e.g., free tier accessing premium)
`404`	Not found — the resource doesn't exist
`429`	Too many requests — you've hit the rate limit
`5xx`	Server error — something went wrong on our end

If you receive a 5xx, the issue is ours. These are rare, but if you encounter one persistently, feel free to reach out in your dashboard. Note that these 5xx errors never count towards your API request usage, if you're on a paid plan.

Rate limits#

Every request counts against a rate limit based on your access tier:

Tier	Limit	Window
Anonymous	30 requests	per day
Free	60 requests	per day
Premium (paid)	1000 requests	per hour

When you hit the limit, you'll receive a 429 response. Check the response headers to understand your current position:

Header	Description	Example
`X-RateLimit-Limit`	Your rate limit allowance	`1000`
`X-RateLimit-Remaining`	Requests remaining this window	`765`
`X-RateLimit-Reset`	Unix timestamp when the window resets	`1767222000`

These headers are included on every response, not just errors, so you can monitor your usage proactively.

Retrying#

Not all errors are worth retrying.

Do retry (with backoff):

429 — Wait until X-RateLimit-Reset, or use exponential backoff
500, 502, 503 — Transient server issues; wait a few seconds and retry

Don't retry:

400 — Your request is malformed; fix it first
401, 403 — Authentication issue; retrying won't help
404 — The resource doesn't exist

For rate limit errors, the simplest approach is to wait until the reset time. If you need something more sophisticated, exponential backoff with jitter works well: wait 1 second, then 2, then 4, adding a small random delay to avoid thundering herd problems if multiple clients reset simultaneously.