Errors
Error body
Errors are returned with an HTTP status code and a JSON body.
{ "code": "...", "message": "..." }code is a stable identifier for programs, message is a description for people. Base your logic on the status code and code, not on the text of message.
Status codes
| Status | Meaning |
|---|---|
400 |
countrycodes is missing or invalid on /search, or a country is not supported |
401 |
The API key is missing, unknown, revoked or expired |
403 |
The request comes from outside the key’s IP rules |
429 |
The rate limit is exceeded. See Rate limits |
503 |
The service is temporarily unavailable. Try again later |
A 400 for a missing countrycodes refers to the documentation. For a country that is not supported yet, you can request it.
Partial results
A search across several countries, or across a country that consists of several shards, is sent to all shards involved. Each shard has a fixed timeout. If a shard does not respond in time, you still get the results of the others, and the response carries the X-Partial-Result header with the missing shards.
X-Partial-Result: de-southThe response body keeps the normal Nominatim format. If completeness matters, check for this header and retry the request.