API DOCUMENTATION / ERRORS AND RESPONSE HEADERS

Errors and response headers

Interpret structured errors, status mappings, usage headers, and conditional rate-limit metadata.

Structured errors

{
  "error": {
    "code": "job_not_found",
    "message": "The requested job was not found.",
    "request_id": "<uuid>"
  }
}

This example represents the source-mapped job-detail 404 shape. Other codes and status mappings depend on route and error class.

Common status codes

HTTP	Meaning in the inspected route source
400	Invalid query/body/identifier or cursor scope.
401	Missing or invalid bearer credential.
404	A requested job, company, or usage key was not found (route-specific).
410	A job detail is marked withdrawn.
308	A merged job/company ID redirects to a canonical ID; job and company response bodies differ.
422	A usage report exceeds source-row or group limits, or a route-specific usage report error occurs.
429	Enforced request-window or monthly-record policy is exceeded; Retry-After is returned.
503	Catalog/projection or service unavailability; HTML description requests are unavailable until confirmed source HTML is provided.

Usage response headers

After usage admission, responses can include X-Request-Id, X-Data-API-Usage-Mode, X-Data-Records-Used, and X-Data-Records-Reset. Enforced request windows add RateLimit-*; a configured returned-record cap can add X-Data-Records-Limit and X-Data-Records-Remaining. Headers depend on policy and usage-snapshot availability; they are not guaranteed on every response.

Recover deliberately

Read the structured error.code and status before retrying. Correct a 400 request rather than retrying it unchanged. Follow Retry-After on 429. A 503 can indicate catalog or projection unavailability or an HTML description request that cannot be served from confirmed source HTML.

Error codes

Every error body is {"error": {"code", "message", "request_id"}}. Branch on code, not on the message.

Code	HTTP	What to do
`invalid_request`	400	A parameter, body or cursor is wrong, or a cursor belongs to an older catalog snapshot. Fix the request or restart from the first page; do not retry it unchanged.
`invalid_api_key`	401	The bearer key is missing, wrong or revoked, or an MCP sign-in token was used on a route it cannot read.
`job_not_found`	404	No job has this ID.
`company_not_found`	404	No company has this ID.
`api_key_not_found`	404	A usage report named an `api_key_id` that is not one of your keys.
`job_withdrawn`	410	The job was withdrawn.
`report_too_large`	422	A usage report covers more than 100,000 events or 1,000 groups. Narrow the period.
`rate_limited`	429	Your 60-second request window is full, or your monthly API requests are used up. Wait for `Retry-After` seconds.
`data_limit_exceeded`	429	This response would go past your monthly allowance, so no data was sent.
`query_timeout`	504	The query did not finish within 10 seconds, including time waiting for a free worker, so it was stopped and no records were charged. Narrow the filters (for example add a state, city, source or company) and try again.
`catalog_unavailable`	503	The jobs catalog is being published. Retry shortly.
`service_unavailable`	503	A temporary failure, or the catalog changed during the request. Retry.
`html_unavailable`	503	`description_format=html` was requested; HTML descriptions are not published. Use `text`.

Codes from the MCP server are on the MCP tools page.

Continue in the reference

Check related request behavior before you build.

View route status and methods Discuss API requirements

All API documentation