Errors & billing

Responses at a glanceCopy Anchor Link

The API never answers 502 or 504. A request that runs out of time is a 500 with reason: job_timeout.

Failure bodiesCopy Anchor Link

Failures share one shape:

{
  "success": false,
  "engine": "google_maps",
  "reason": "captcha",
  "total_attempts": 5
}

An error in the service itself has a message such as Search failed due to server error and no reason. A 400 adds error with the reason in words.

reason valuesCopy Anchor Link

place_page is no longer sent: a Google Maps search that matches exactly one place now answers that place.

Place details errorsCopy Anchor Link

Maps place failures also carry error: {code, message} beside reason. code is one of place_not_found, error, captcha, consent_wall, blocked, timeout or no_capacity. A 404 with error.code: place_not_found is the only answer that means the place is gone.

{
  "success": false,
  "engine": "google_maps_place",
  "reason": "profile_not_found",
  "error": { "code": "place_not_found", "message": "Google has no place with this id" },
  "total_attempts": 2
}

Retry guidanceCopy Anchor Link

• Retry 500, 503 and 200 with parsed: false. Back off between tries; each retry is a full job.
• On 503, retry after a pause, or after Retry-After seconds when it is sent.
• On 429, retry when one of your requests finishes, or after a second or two. See Rate limits.
• Do not retry 400, 401, 403, 404 or 422.
• A 500 profile_not_found was seen once and not confirmed, so one retry is reasonable.
• Google AI Overview: an empty Overview is an answer, not a failure.
• Set your client timeout to about 100 seconds so a late answer is not cut off.

CancellingCopy Anchor Link

Send a cancel_token of your own with a request. Later, GET /v1/cancel?cancel_token=<token> with the same token stops the job before its next attempt (never mid-page) and the original request answers 499. Tokens are private to your API key. Use a new token for every request, retries included: a cancelled token stays cancelled for a few minutes.

curl -G "https://api.justserp.com/v1/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "cancel_token=7f3c2a9e-4b1d-4e8a-9c6f-2d5b8a1e0f43"

BillingCopy Anchor Link

A 200 costs a call, and so does a 404: the profile or place you asked for does not exist, which takes the same work to find out. Every other answer is free, including 400, 422, 499, 500 and 503, and refusals (401, 403 and 429) are never counted. Retrying a failed request never pays twice for the same failure.

Calls are counted from your key's balance as they are served. Every 200 carries X-RateLimit-Remaining, the calls left after that request; it can trail your dashboard by a few minutes. /v1/google/locations is free.

If your client hangs up before the answer, the job is stopped and the call is still charged, because the work was done. Set a client timeout of about 100 seconds rather than a shorter one, and use cancelling when you no longer want an answer.