My Geocode

Guides

Retry a failed lookup the right way

· 2 min read · My Geocode · #errors#retries#reliability

An automatic retry is the right move for some errors and a waste of a request for others. Getting this wrong either floods a struggling endpoint or gives up on a lookup that would have worked a second later.

Errors that are worth retrying

A 503 response means the service is temporarily unavailable, which is exactly the kind of transient condition a short delayed retry is built for. A network timeout on your own end, where you never received a response at all, falls into the same category, since the request may or may not have been processed.

HTTP/1.1 503 Service Unavailable

{
  "status": "error",
  "error": {"code": "service_unavailable", "message": "Temporarily unavailable, try again shortly"}
}

Errors that are not worth retrying

A 400 means the request itself was malformed, such as a missing required parameter or coordinates out of range. A 401 means authentication failed. Retrying either of those without fixing the underlying problem just produces the same error again, and each attempt still counts as a request in most cases, so a retry loop against a bad request can burn through your allowance for nothing.

Backing off between attempts

A fixed short delay is fine for a single interactive lookup, but a batch job retrying many failed items should back off progressively, doubling the wait between attempts up to a reasonable ceiling, so a brief outage does not turn into a flood of retries the moment service resumes.

429 is its own case

A 429 is not really a failure to retry so much as a signal to pause. Read the X-Quota-Reset header and wait until then rather than retrying on a short fixed delay, since retrying before the reset will just produce the same 429 again and again.

Keeping request cost in mind

Every retry attempt that reaches the server, successful or not, is a request. A retry strategy that respects the difference between transient and permanent errors keeps your daily allowance and prepaid credit spent on real work rather than repeated failures.

Distinguishing "try again" from "fix this first" is most of what a good retry strategy comes down to. The errors page lists every error code the API returns and what triggers each one.

More in Guides