Error Codes

HTTP status codes and error responses you may encounter.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of a request:

Code	Name	Description
`200`	Success	The request was successful.
`400`	Bad Request	The request was malformed or missing required parameters.
`401`	Unauthorized	Missing or invalid API key.
`404`	Not Found	The requested resource does not exist.
`429`	Rate Limited	Daily limit exceeded. Wait until reset or upgrade your plan.
`500`	Server Error	An unexpected error occurred on our servers.

Each error returns a JSON response with details:

401Unauthorized

json

{
  "error": "unauthorized",
  "message": "Invalid API key. Get your key at localityapi.com"
}

400Bad Request

json

{
  "error": "bad_request",
  "message": "Missing required parameter: q"
}

404Not Found

json

{
  "error": "not_found",
  "message": "No results found for the given query"
}

429Rate Limited

json

{
  "error": "rate_limit_exceeded",
  "message": "Daily limit reached. Upgrade at localityapi.com/pricing",
  "reset_at": "2026-05-29T00:00:00Z"
}

500Server Error

json

{
  "error": "server_error",
  "message": "An unexpected error occurred. Please try again."
}

Best practices for handling API errors in your application:

Check status codes — Always check the HTTP status code before processing the response.
Parse error messages — Display meaningful error messages to users based on the error response.
Retry on 5xx errors — Server errors are usually temporary. Implement retry logic with exponential backoff.
Log errors — Log error responses for debugging and monitoring purposes.