Geocode Unavailable
geocode_unavailable503
Location-name search is temporarily down. If you have lat/lon, use them directly — most endpoints accept either.
What this means
We received a request that needed to convert a location name (like "Mumbai" or "Brooklyn, NY") into coordinates, and the geocoding provider we use is unreachable or returned an error. This error fires before any astrological calculation begins, so no chart was partially built — the request just couldn't get past the location-resolution step.
When you'll see this
- The geocoding provider (currently Nominatim) is rate-limiting our IP or is briefly down.
- The provider responded but with a malformed response we couldn't parse.
- Network connectivity between our API and the geocoder timed out.
- We're rolling out a geocoder change and a transient gap occurred.
Learn more about how this works
Geocoding is a soft dependency. Asterwise calculations need precise latitude, longitude, and timezone — not a location name. We accept names as a convenience because typing "Mumbai" is easier than typing 19.0760, 72.8777, Asia/Kolkata every time. When the convenience layer breaks, the calculation layer is unaffected.
In practice: if you're already storing user locations as lat/lon/timezone tuples (which you should for any production system handling repeated birth-data lookups), this error won't reach your users at all.
Example response
{
"success": false,
"error": "geocode_unavailable",
"message": "Location search is temporarily unavailable. Please try again shortly.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/geocode_unavailable",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- If you have the latitude, longitude, and timezone for the location already, re-send the request using those fields directly instead of the location name.
- If you only have the name, wait 30-60 seconds and retry — geocoder outages are usually short.
- If geocoding stays broken for more than a few minutes, check status.asterwise.com for an active incident.
Treat geocoding as a best-effort lookup. Always store the resolved coordinates after the first successful geocode so subsequent requests skip the lookup entirely. On a fresh geocode failure, retry once with backoff, then surface a location-picker UI to the user.
Python:
Production handler
- Python
- TypeScript
import httpx
import time
def resolve_location(query, base_url, headers, cached_coords=None):
if cached_coords:
return cached_coords
for attempt in range(2):
response = httpx.get(
f"{base_url}/v1/utils/geocode",
headers=headers,
params={"q": query},
timeout=10,
)
if response.status_code == 503:
body = response.json()
if body.get("error") == "geocode_unavailable":
time.sleep(30)
continue
return response.json()
raise RuntimeError("Geocoder unavailable. Use lat/lon directly.")
async function resolveLocation(
query: string,
baseUrl: string,
headers: HeadersInit,
cachedCoords?: { lat: number; lon: number; timezone: string },
) {
if (cachedCoords) return cachedCoords;
for (let attempt = 0; attempt < 2; attempt++) {
const response = await fetch(
`${baseUrl}/v1/utils/geocode?q=${encodeURIComponent(query)}`,
{ headers },
);
if (response.status === 503) {
const body = await response.clone().json();
if (body.error === "geocode_unavailable") {
await new Promise((r) => setTimeout(r, 30_000));
continue;
}
}
return response.json();
}
throw new Error("Geocoder unavailable. Use lat/lon directly.");
}
Avoid this error by
- Cache geocode results on your side. A location name resolves to the same coordinates every time — there's no reason to call the geocoder twice for the same input.
- Store user-entered birth locations as
{lat, lon, timezone}tuples after the first geocode, not as raw strings. Every downstream chart calculation will be faster and immune to this error. - For high-volume use cases, prefer lat/lon input directly. The geocode endpoint is convenience, not a hard requirement.