Error Handling
What the API returns when a call fails, and how to react. Errors are never billed: only HTTP 200 responses cost credits.
Error Response Format
Every error has the same envelope: a machine-readable error code and a human-readable message.
{
"detail": {
"error": "place_not_found",
"message": "Google has no place with this identifier"
}
}Read the code from detail.error, not from the message: messages can change, codes do not. Some errors add fields next to them, such as available and required on 402 and retry_after on 429.
Validation errors (422) come from the framework and have a different shape: detail is a list, one entry per invalid parameter, with its location, a message and a type.
{
"detail": [
{
"type": "less_than_equal",
"loc": ["query", "limit"],
"msg": "Input should be less than or equal to 20",
"input": "50",
"ctx": { "le": 20 }
}
]
}A 429 can also come from our edge proxy when a burst of requests arrives at once; that response may have a plain-text body instead of JSON. Treat every 429 the same way: wait and retry.
HTTP Status Codes
Bad Request
The request has an identifier, cursor or location the API cannot use.
Do not retry: fix the request.
invalid_place_id — The place is not a place ID (ChIJ…), a CID or a feature ID (0x…:0x…), or the URL given to resolve does not identify a single place.invalid_cursor — The cursor is malformed, expired or was produced by a different request.invalid_location — lat was given without lng, or the other way round.Unauthorized
The API key is missing or not valid.
Do not retry: check the X-API-Key header and that the key is enabled.
missing_api_key — No X-API-Key header (or Authorization: Bearer) in the request.invalid_api_key — The key does not exist, has been deleted or is disabled.Payment Required
Your account has no credits left for this call.
Add credits in the dashboard, then retry.
insufficient_credits — The balance is below the cost of the call. detail also carries available (credits left) and required (credits needed).Not Found
The place does not exist on Google Maps or has been removed.
Do not retry with the same identifier.
place_not_found — No place matches this identifier.Validation Error
A parameter is missing or out of range, e.g. limit above the maximum or a region that is not 2 letters.
Do not retry: detail is a list with one entry per invalid parameter (see the example above).
Too Many Requests
You sent more than 500 requests per minute, or kept calling with no credits left.
Wait for the number of seconds in the Retry-After header, then retry.
rate_limit_exceeded — Per-minute rate limit reached. detail.retry_after repeats the Retry-After seconds.insufficient_credits_retry_later — Repeated calls without credits: the key is paused for a short time. Top up; requests are accepted again within seconds.Internal Server Error
An unexpected error on our side.
Retry once after a few seconds; if it persists, contact support with the time of the request.
internal_server_error — Unexpected error. You were not charged.Upstream Error
Google answered with an unexpected error.
Retry after a few seconds with exponential backoff.
upstream_error — Temporary error while contacting Google Maps. You were not charged.proxy_error — A maps.app.goo.gl short link could not be followed (resolve only). You were not charged.Service Unavailable
Google Maps is temporarily unreachable from every route we use.
Retry in a minute.
upstream_unavailable — All providers failed or are cooling down. You were not charged.Retrying
Retry only 429, 502 and 503, with backoff; honour Retry-After when present. Retried calls that fail cost nothing.
import time
import requests
RETRYABLE = {429, 502, 503}
def call(path, params=None, retries=5):
for attempt in range(retries):
r = requests.get(
f"https://api.scrapemapsapi.com{path}",
headers={"X-API-Key": "key_your_api_key"},
params=params,
timeout=60,
)
if r.status_code == 200:
return r.json()
if r.status_code not in RETRYABLE:
# {"detail": {"error", "message"}}, or a list of invalid parameters on 422
raise RuntimeError(f"{r.status_code} {r.json()['detail']}")
# A 429 from the edge proxy can have a plain-text body: rely on the status and Retry-After
time.sleep(int(r.headers.get("Retry-After", 2 ** attempt)))
raise RuntimeError("Gave up after retries")Need Help?
If an error persists, write to [email protected] with the time of the request and the error code, or check the API reference.