Errors

Every error returns JSON with success: false and a readable message. A 422 also lists each invalid field.

Agents & LLMs: a Markdown version of this page is available by appending .md to the URL, and the full documentation index is at llms.txt.

Status codes

Code	Meaning	What to do
`400`	Bad Request	The request body is not valid JSON. Send a JSON object with the header `Content-Type: application/json`.
`401`	Unauthorized	Missing or invalid `x-api-key` header.
`402`	Payment Required	Account limit reached. Upgrade your plan.
`404`	Not Found	API key does not exist.
`422`	Unprocessable Entity	A request field is unknown or has an invalid value. Fix the fields listed in `errors` and resend. See below.
`429`	Too Many Requests	Exceeded an endpoint’s rate limit. Throttle client-side to your plan’s `max_requests_per_seconds`.
`500`	Internal Server Error	Transient server error. Retry with exponential backoff.
`503`	Service Unavailable	The service is temporarily unavailable. Retry with exponential backoff.

Only 429, 500, and 503 are worth retrying as-is. A 400 or 422 fails the same way until you change the request.

Validation errors (422)

The API checks the request body before it runs the request, so a 422 never uses records. A body is rejected when it contains:

A field the endpoint does not define, at any depth. A misspelled filter such as company.industry.includes returns a 422 instead of being ignored.
A value outside an accepted list, such as an industry, job level, or employee range. These values are case-sensitive: copy them from Field Normalization.
A wrong type or an out-of-range value, such as a string for max_results or more than 50 items in a filter list.

Invalid value

{
  "success": false,
  "message": "Invalid request body. company.industry.include[0]: Invalid value \"Software\". Did you mean \"Computer Software\", \"Software Development\" or \"Embedded Software Products\"?",
  "errors": [
    {
      "field": "company.industry.include[0]",
      "message": "Invalid value \"Software\". Did you mean \"Computer Software\", \"Software Development\" or \"Embedded Software Products\"?"
    }
  ]
}

Field	Type	Description
`success`	`boolean`	Always `false`.
`message`	`string`	One-line summary of the first three errors, for logs.
`errors`	`array`	One item per problem, up to 20.
`errors[].field`	`string`	Path to the problem. Dots mark nesting and `[n]` marks an array item, e.g. `company.industry.include[0]`.
`errors[].message`	`string`	What is wrong. When the input is close to a valid field or value, it suggests the closest match. Otherwise a short list of allowed fields or values is given in full.

For an unknown field, field is the object that contains it (body for a top-level field) and message names the rejected field:

Unknown field

{
  "success": false,
  "message": "Invalid request body. company.industry: Unknown field \"includes\". Did you mean \"include\"?",
  "errors": [
    {
      "field": "company.industry",
      "message": "Unknown field \"includes\". Did you mean \"include\"?"
    }
  ]
}

Read errors[].field to find what to fix, and treat message as text for humans: its wording can change.

Free-text filters such as name, keywords, job_title, city, and country_code are not checked against a list. A typo in one of them is not an error: the search runs and returns 0 results. See Troubleshooting.

Introduction

Getting Started

Core Concepts

Recipes (Use Cases)

Integrations

Appendix

Errors

Errors

Status codes

Validation errors (422)

​Errors

​Status codes

​Validation errors (422)

Errors

Status codes

Validation errors (422)