Reference

Errors and recovery

Public API failures use one response envelope so clients can tell validation, authentication, quota, rate-limit, and server outcomes apart.

Error shape

{
  "code": 422,
  "msg": "Invalid parameter format or value",
  "data": null
}

HTTP status reference

HTTP: 400
Meaning: Invalid or missing request parameters, including a refused query tree
Client action: Correct the request before retrying

HTTP: 401
Meaning: Missing or invalid API key
Client action: Provide a valid Bearer key

HTTP: 402
Meaning: Credits exhausted
Client action: Review quota and plan state

HTTP: 403
Meaning: Key disabled, expired, or missing scope
Client action: Use an active key with the required scope

HTTP: 404
Meaning: Route or selected record not found
Client action: Check the path or omit unavailable records

HTTP: 422
Meaning: Invalid parameter format or value
Client action: Fix the named field

HTTP: 429
Meaning: Rate limit exceeded
Client action: Back off before retrying

HTTP: 500
Meaning: Internal server error
Client action: Retry only with bounded backoff

HTTP: 503
Meaning: Capability unavailable
Client action: Treat the feature as unavailable

HTTP	Meaning	Client action
400	Invalid or missing request parameters, including a refused query tree	Correct the request before retrying
401	Missing or invalid API key	Provide a valid Bearer key
402	Credits exhausted	Review quota and plan state
403	Key disabled, expired, or missing scope	Use an active key with the required scope
404	Route or selected record not found	Check the path or omit unavailable records
422	Invalid parameter format or value	Fix the named field
429	Rate limit exceeded	Back off before retrying
500	Internal server error	Retry only with bounded backoff
503	Capability unavailable	Treat the feature as unavailable

Query Spec refusals

A query tree is translated before anything runs, so these all arrive as a 400 and none of them cost a Credit. The Query Spec page explains the grammar behind each one.

Message: At least one search condition is required.
What triggered it: An empty where tree
Fix: Add a condition. An unfiltered sweep of the corpus is not available

Message: Unsupported query field. See the documented field list.
What triggered it: A field name that is not in this dataset's list
Fix: Check the dataset's field table. The three datasets do not share one vocabulary, so a name from another one is refused here

Message: Unsupported operator. Allowed: eq, in, match, gte, lte, exists.
What triggered it: Two operators in one leaf, no operator, an operator the field does not accept, or a number sent as a string
Fix: One operator per leaf, matched to the field kind. Split a bounded range into an all of two leaves

Message: Each query node must be one of: all, any, not, a scope, or a field condition.
What triggered it: A node shape the grammar does not have, or an extra key on a leaf
Fix: Remove the extra key, or wrap the conditions in a composer

Message: Unsupported date value. Use YYYY-MM-DD or a documented relative value such as now-6m.
What triggered it: A date form outside the documented set, or an offset past the maximum
Fix: Use YYYY-MM-DD, or now-<n>d, now-<n>m, now-<n>y inside the published limits

Message: Field is not available inside <scope>.
What triggered it: A field used inside a scope that does not group it
Fix: Move the condition outside the scope, or use a field the scope covers

Message: Nested scopes cannot be nested inside one another.
What triggered it: has_experience inside has_education, or similar
Fix: Keep scopes at the same level and combine them with all or any

Message: Query nesting exceeds the maximum depth of 6.
What triggered it: A tree nested deeper than six levels
Fix: Flatten the tree. Most queries need two or three levels

Message: Query exceeds the maximum of 64 conditions.
What triggered it: More than 64 leaves in one tree
Fix: Split the work across several queries, or use in with a list instead of many any branches

Message	What triggered it	Fix
At least one search condition is required.	An empty where tree	Add a condition. An unfiltered sweep of the corpus is not available
Unsupported query field. See the documented field list.	A field name that is not in this dataset's list	Check the dataset's field table. The three datasets do not share one vocabulary, so a name from another one is refused here
Unsupported operator. Allowed: eq, in, match, gte, lte, exists.	Two operators in one leaf, no operator, an operator the field does not accept, or a number sent as a string	One operator per leaf, matched to the field kind. Split a bounded range into an all of two leaves
Each query node must be one of: all, any, not, a scope, or a field condition.	A node shape the grammar does not have, or an extra key on a leaf	Remove the extra key, or wrap the conditions in a composer
Unsupported date value. Use YYYY-MM-DD or a documented relative value such as now-6m.	A date form outside the documented set, or an offset past the maximum	Use YYYY-MM-DD, or now-<n>d, now-<n>m, now-<n>y inside the published limits
Field is not available inside <scope>.	A field used inside a scope that does not group it	Move the condition outside the scope, or use a field the scope covers
Nested scopes cannot be nested inside one another.	has_experience inside has_education, or similar	Keep scopes at the same level and combine them with all or any
Query nesting exceeds the maximum depth of 6.	A tree nested deeper than six levels	Flatten the tree. Most queries need two or three levels
Query exceeds the maximum of 64 conditions.	More than 64 leaves in one tree	Split the work across several queries, or use in with a list instead of many any branches

Errors and recovery

Error shape#

HTTP status reference#

Query Spec refusals#

Error shape

HTTP status reference

Query Spec refusals