Errors & Status Codes

Every API response returns a standard HTTP status code. On success you get a JSON body with your data. On failure you get a JSON body with error and message fields explaining what went wrong.

Status Codes

Code	Meaning	What to Do
200	Success	Request completed. Parse the response body.
400	Bad Request	A required parameter is missing or invalid. Check the message field for details.
401	Unauthorized	Your API key is missing, invalid, or revoked. Verify your key starts with sk_live_ and is included in the Authorization header.
402	Insufficient Credits	Your account balance is too low for this request. Add credits at localseodata.com/dashboard/billing or upgrade your plan.
429	Rate Limited	You've exceeded your plan's rate limit. Back off and retry after the interval in the Retry-After header.
500	Server Error	Something went wrong on our end. Retry with exponential backoff. If it persists, contact support.

Error Response Format

All errors return this structure:

{
  "status": "error",
  "error": "INSUFFICIENT_CREDITS",
  "message": "This request costs 50 credits but your balance is 12. Add credits or upgrade your plan."
}

Common Error Scenarios

"Invalid location" -- The location string couldn't be resolved. Use the Location Search endpoint to find the exact format, or try "City, State" format (e.g. "Buffalo, NY").

"Business not found" -- No Google Business Profile matched your query. Try adding the city, or use a place_id for exact matching. The Business Profile endpoint returns suggestions when no exact match is found.

"Rate limit exceeded" -- Each plan has per-minute and per-day limits. The response includes a Retry-After header with the number of seconds to wait. See Rate Limits for plan-specific thresholds.

Retry Strategy

For 429 and 500 errors, use exponential backoff:

1. Wait 1 second, retry
2. Wait 2 seconds, retry
3. Wait 4 seconds, retry
4. After 3 failed retries, log the error and alert

Do not retry 400 or 401 errors -- these require fixing the request itself.