Geocode Query Too Short
geocode_query_too_short422
Location search needs at least 2 characters. Provide a longer query.
What this means
A geocoding request was made with a query string shorter than 2 characters. We reject it before sending to the geocoder — single-character queries return enormous result sets that are nearly always useless and waste both our bandwidth and the geocoder's quota. The minimum-length check is structural; longer queries proceed to the geocoder normally.
When you'll see this
- An autocomplete sent a request after the first character of typing (before debouncing kicked in).
- A search field's value was a single character (incomplete user input).
- A whitespace-only query was submitted (no real characters at all).
- An automated process generated empty or stub queries by accident.
Learn more about how this works
Two-character minimum is a small but meaningful efficiency. The geocoder we use has its own rate limits, and single-character queries effectively burn quota for results no user will ever scroll through. By rejecting them at our edge, we avoid wasting downstream resources and respond faster to the caller.
In practice: this error is almost always a UX issue — an autocomplete firing too eagerly, or a search button enabled with no input. Fix it on your side by debouncing or requiring a minimum length before triggering the geocoder.
Example response
{
"success": false,
"error": "geocode_query_too_short",
"message": "Search query must be at least 2 characters.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/geocode_query_too_short",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Verify the query string is at least 2 non-whitespace characters before sending.
- If you have an autocomplete, add a minimum-length guard so it doesn't fire on the first character.
- If you have a search button, disable it until the input has at least 2 characters.
Client-side validation makes this error essentially unreachable.
Python:
Production handler
- Python
- TypeScript
import httpx
def geocode(query, base_url, headers):
query = query.strip()
if len(query) < 2:
return {"results": [], "reason": "query too short"}
response = httpx.get(
f"{base_url}/v1/utils/geocode",
headers=headers,
params={"q": query},
timeout=10,
)
response.raise_for_status()
return response.json()
async function geocode(query: string, baseUrl: string, headers: HeadersInit) {
const trimmed = query.trim();
if (trimmed.length < 2) {
return { results: [], reason: "query too short" };
}
const response = await fetch(
`${baseUrl}/v1/utils/geocode?q=${encodeURIComponent(trimmed)}`,
{ headers },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
Avoid this error by
- Debounce autocomplete inputs (200-300ms is typical). Users finish typing before the request fires.
- Require minimum input length before enabling search. Don't fire on the first keystroke.
- Trim whitespace before checking length — a query of
" a "is structurally 1 character, not 3. - For programmatic geocoding (batch processing, etc.), validate query length in your data prep step, not at the HTTP boundary.