Reference
Errors & edge cases
Status codes
| Status | Meaning |
|---|---|
200 OK | Success. The body may be an empty array if nothing matched. |
403 Forbidden | Missing or invalid apiKey, or the calling domain is not allow-listed. |
403 responses
Code(json)
Code(json)
The first is returned when apiKey or the domain could not be determined; the
second when the (domain, apiKey) pair is not on the allow-list. See
Authentication.
Empty results
An empty array is a 200, not an error
Search and structured search return 200 with [] when:
- there are no matching addresses, or
- the active field is blank (structured search), or
- the client cancels the request before it completes.
Always check for an empty array rather than relying on a non-200 status to
detect "no results".
Recommendations
Debounce input
Send a request only after a short pause in typing (≈150–250 ms) to reduce load and cost.
Cancel stale requests
Use AbortController (or your client's equivalent) to cancel superseded
requests; the API already treats a cancelled request as an empty result.
Bias by location
Pass lon/lat whenever you have a rough location — it markedly improves the
ordering of suggestions.
Last modified on