Skip to main content
Errors return JSON with success: false and a readable message, except a 423 and an unknown path (see below). A 422 also lists each invalid field, and every JSON error body carries a fair_usage block.
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

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

Usage block on errors

Every JSON error body of a /v2 endpoint carries fair_usage, the same block as on a successful response:
401
Read the last three fields as optional: they are absent when the request stops before your plan is read, such as on a 401.

Response headers

Every response, errors included, carries an X-Request-Id header: quote it when you contact support. On a 200 and in every JSON error body, fair_usage.request_id holds the same value.

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, except industries, which ignore case and also accept other known spellings of a label: 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.
  • A combination that cannot match, such as a range with min above max, or include_active_jobs and include_past_jobs both set to false.
Invalid value
For an unknown field, field is the full path to the unknown key (a top-level key gives its own name, such as compnay) and message suggests the closest valid field, or lists the allowed fields when none is close:
Unknown field
A null reads the same as leaving the field out, at any depth, including inside the objects of a list: the field’s default applies (max_results: null gives the endpoint’s default, country_code: null on Employee Finder gives ["WORLD"], and cascade[].location: null on Waterfall ICP searches the whole world), and an unknown field set to null is ignored instead of returning a 422. A null on a required field, or a null item inside a list, still returns a 422.
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. Only the length of a country_code is checked: a value that does not have two letters, such as USA or United Kingdom, returns a 422 (WORLD is the one exception). See Country Codes and Troubleshooting.