Errors and Quota Headers

Search errors use stable machine-readable codes so callers can distinguish validation, auth, quota, coverage, and layer selection failures without parsing prose messages. Every error body carries code, message, request_id, and docs_url, a link to that code's entry on this page (https://openplacesapi.com/docs/errors#<code>). Validation errors add details, a list of field and message pairs for each rejected parameter.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid search request.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": [
      { "field": "radius_mi", "message": "radius_mi must be greater than 0 and at most 50." }
    ],
    "docs_url": "https://openplacesapi.com/docs/errors#validation_error"
  }
}

quota_exhausted also returns quota_limit and upgrade_url. Buy more searches from the dashboard billing page. There is no reset date or automatic charge.

{
  "error": {
    "code": "quota_exhausted",
    "message": "No searches left on this account. Buy more at https://app.openplacesapi.com/#billing.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "quota_limit": 2500,
    "upgrade_url": "https://app.openplacesapi.com/#billing",
    "docs_url": "https://openplacesapi.com/docs/errors#quota_exhausted"
  }
}

Search errors link to their row through docs_url. Branch on code, not on message; messages can change wording.

Management and billing responses from app.openplacesapi.com use a different shape: {"error":{"code":"…","message":"…"}}, without the search API's request_id or docs_url fields. The two management and billing codes below are marked in their descriptions.

When a response includes Retry-After, wait at least that many seconds before retrying. For rate_limited it is the time until the burst window resets, or 1 when the account hit the concurrency cap. For 503 codes it is a short backoff hint. quota_exhausted has no Retry-After or reset date. Stop and buy more at upgrade_url.

Each account can have at most 8 searches in flight at once. Requests over the cap are rejected immediately with rate_limited and are not billed. Bound client-side parallelism to stay under the cap.

Successful searches can include meta.warnings, a list of code and message objects. Warnings do not change the HTTP status. unknown_category and no_results_within_radius are only added to an empty first page (offset=0 with no results).

{
  "warnings": [
    {
      "code": "unknown_category",
      "message": "\"coffeeshop\" is not a known category. Closest known categories: coffee_shop. List categories with GET /v1/categories?q=<text>.",
      "suggestions": ["coffee_shop"]
    }
  ]
}

X-Quota-Limit and X-Quota-Remaining are sent on successful searches and quota_exhausted responses. Other failures, including invalid keys and validation errors, do not carry quota headers.