Errors & status codes
countries.dev uses standard HTTP status codes. Learn what 200, 400, 404 and 429 mean, how errors are returned as JSON, and how to handle a missing country gracefully.
countries.dev uses conventional HTTP status codes and returns errors as a small JSON object.
Status codes
| Code | Meaning | When you'll see it |
|---|---|---|
200 | OK | The request succeeded. |
400 | Bad request | A parameter is invalid — e.g. a non-numeric value where a numeric code is expected. |
404 | Not found | Nothing matches — an unknown ISO code, an unmatched postal code, or a country with no results. |
429 | Too many requests | You hit the abuse ceiling. See Rate limits & caching. |
Error shape
Errors come back as JSON with an error message:
{
"error": "Country not found"
}Handling errors
Check response.ok (or the status code) and branch on it:
const res = await fetch('https://countries.dev/alpha/ZZ');
if (res.status === 404) {
// No country with that code — show a fallback.
} else if (res.ok) {
const country = await res.json();
}A 404 usually means the input didn't match anything (a typo'd ISO code, a postal code we don't cover) rather than a server problem — treat it as "no result", not "try again".
Response format
Every countries.dev endpoint returns JSON. Learn how to select fields, sort and paginate the country API response with the fields, sort, order, limit and offset query parameters.
Rate limits & caching
countries.dev has no per-key rate limits or quotas — only a generous abuse ceiling. Responses are cached at the edge for speed. Learn the Cache-Control headers and how to cache in your app.