DEVELOPER DOCUMENTATION

Errors and limits

Every error has a stable code and a short message.

Error shape

JSON

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Provide a valid Bearer API key."
  }
}

Codes

Code	Status	Meaning
`INVALID_API_KEY`	401	The key is missing, unknown or revoked
`KEY_SCOPE`	403	The key cannot do this, or cannot use this index
`ORIGIN_NOT_ALLOWED`	403	A browser key used from a website it does not list
`INVALID_INPUT`	422	The query is empty, too long, or the locale is not en or ar
`INVALID_SEARCH`	422	A malformed search or area
`BETA_REQUIRED`	403	Hosted search is not enabled for the account
`NO_SUCH_INDEX`	404	The index does not exist
`CONFIRMATION_REQUIRED`	409	An import that would remove more than 20% needs confirming
`PLAN_LIMIT`	402	Beyond the plan: indexes, published rules, campaigns
`PLAN_REQUIRED`	402	Hosted search needs a plan: the free period and grace period ended
`RATE_LIMITED`	429	Too many requests; retry after `Retry-After` seconds
`DAILY_LIMIT`	429	The free Developer API key's daily allowance is used up
`TOO_MANY_INVALID_KEYS`	429	Too many attempts with invalid keys from one address; try again later
`BUDGET_EXHAUSTED`	503	The service's monthly budget is reached; parsing resumes when it resets
`INVALID_LISTING`	422	A listing that cannot be used, with its issues
`PARSER_UNAVAILABLE`	503	Parsing is briefly unavailable; retry

Limits

Developer API (free): a daily allowance per key for parse and autocomplete, resetting at 00:00 UTC; each answer carries X-RateLimit-Limit and X-RateLimit-Remaining.

Hosted search (beta and paid plans): no daily allowance. Requests count against the plan's monthly fair-use line (Settings → Usage), with bursts limited per account (50 a second on the free beta) and per visitor of a browser key.