Errors return JSON withsuccess: falseand a readablemessage, except a423and an unknown path (see below). A422also lists each invalid field, and every JSON error body carries afair_usageblock.
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 anX-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 a422 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.includesreturns a422instead 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_resultsor more than 50 items in a filter list. - A combination that cannot match, such as a range with
minabovemax, orinclude_active_jobsandinclude_past_jobsboth set tofalse.
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
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.
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.
