Business Search error codes

Look up every HTTP status Business Search returns, 200 to 504, with its cause, whether to retry and what to fix, plus two sample 400 rejection bodies.

This page is the status code table for Business Search. A Business Search error is a JSON body with an error message, never a successful search with zero matches. HTTP 200 with an empty documents array means the search ran and found nothing.

Which status codes does Business Search return?

Status	Meaning	Retry	What to do
200	The search ran. documents can still be empty	Not needed	Treat an empty documents array as no matches, not as an error and not as proof the entity does not exist
400	The request body is invalid	Never	Fix the field, operator, mode or pagination value named in error
401	The API key is missing, invalid or expired. A wrong key returns {"error":"Invalid token"} and an expired one returns Token expired	Never	Check the key in the Control Panel
403	The account cannot use Business Search: no customer account exists for the key, the account is inactive or the account is not on the API allowlist	Never	Confirm the account is active and has Business Search access
404	Unknown API version	Never	Correct the version segment in the request path
429	The rate limit was exceeded. The request was not searched and was not billed	After the delay in Retry-After	Wait the seconds given in the Retry-After header, then send the request again
500	Server-side configuration or backend error	Bounded backoff	Retry. If error_code is backend_search_failed and the same request fails again, the request itself is the cause: in Instant and Smart mode a request whose offset plus limit exceeds 100 returns this error, so change the request instead of retrying it
501	The request is valid but unsupported: the source is disabled or unavailable, or natural-language planning or ranking is not available for that source	Never	Change the mode or the source
502	The natural-language planner or the ranking step returned an invalid or empty response. Applies to instant and smart	Bounded backoff	Retry, or send the same search as structured conditions in ludicrous
504	The search timed out	Bounded backoff	Retry with a narrower query

Bounded backoff means a fixed number of attempts with growing delays, never an unlimited loop. Only HTTP 200 responses are billed, because billing requires a completed search. See Business Search pricing for the billable and non-billable request list.

Some responses also carry an error_code, a machine-readable class such as invalid_query or backend_search_failed. Branch on error_code when it is present and fall back to the HTTP status when it is not, because generic errors omit it.

Keep HTTP 400, HTTP 401 or 403, HTTP 429, HTTP 500 to 504 and HTTP 200 with an empty documents array apart in your own logging. Collapsing them into one “search failed” branch hides the difference between a bug in your query and an outage. Log req_id when the response returns one and include it, with the status and the error message, in any support ticket.

Why was a request rejected?

Business Search rejects an invalid request body with HTTP 400 and names what it rejected in error. The causes are:

• An unknown category
• An invalid mode, query, view, offset or limit
• An unknown view profile name, or unknown field names in view
• A natural-language query longer than 200 characters
• An operator the field type does not support, such as equals on a text field
• A debug property such as explain that the account cannot send

Selecting an unknown output field returns:

{
  "error": "view: unknown field(s): not_a_released_field"
}

An operator the field type does not support is rejected the same way. The message names the field, the operator and the types that operator accepts:

{
  "error": "Invalid query: In operator 'equals', field 'industry': Operator does not support field type 'text'. Supported types: bool, byte, double, float, int, language, long, string."
}

Text fields such as industry and current_title accept only the text operator. See Business Search query syntax for the operator each field type accepts.

Correct the request when validation fails. Rate-limit checks run after validation, so a rejected request does not consume rate-limit budget and is not billed, but repeating an invalid body still cannot succeed.

What happens when the rate limit is exceeded?

Business Search returns HTTP 429 with a Retry-After header giving the seconds to wait. Wait that long before retrying. A rate-limited request is not searched and not billed.

The limit is counted per account, per category and per mode, so a company search that is rate limited does not block a people search. The limit value and its scope are listed under What is the rate limit? in the Business Search introduction.

Frequently asked questions

Does a 200 response mean the query was understood?

No. A 200 means the search ran. In Instant and Smart modes, natural-language intent and result relevance are not guaranteed by a successful HTTP response, so review the records before acting on them.

How do I tell a missing field from an empty result?

A missing field inside a returned record means the source has no stored value for that record. An empty documents array means no record matched the conditions. Handle absent values per record and empty pages per request.