Errors, limits & usage

Errors

Errors return a non-2xx status and a JSON body with a readable message:

json

{ "error": "province: Unknown value: XX" }

The feed endpoints (/v1/active-ats and the others under Feeds) describe request errors as application/problem+json (RFC 7807):

json

{
  "type": "https://httpproblems.com/http-status/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Unknown query parameter "timeframe". Did you mean 'time_frame'? See the API reference for the full list of supported parameters for this endpoint.",
  "instance": "/v1/active-ats"
}

Parameter	Type	Description
400	Bad request	A parameter is invalid. The message says which one.
401	Unauthorized	The API key is missing, malformed or revoked.
402	Payment required	The free trial ended and no plan is active. Choose a plan in the dashboard.
404	Not found	Unknown endpoint or job ID.
429	Too many requests	Either the per-second rate limit (wait for `Retry-After` seconds) or the period allowance is used up (`quota_exceeded` is set).
502	Bad gateway	The jobs service is temporarily unavailable. Retry with backoff. These requests are not counted.
504	Gateway timeout	A feed query ran past its time limit (30 seconds; 60 for counts and expired ids). Narrow the filters or time frame, or use cursor pagination.

Usage allowances

Each plan includes a number of jobs and API requests per period: a calendar month from your subscription date, or the 7-day trial.

Every request counts once, including ones that return 4xx errors. Our own failures (5xx) are not counted.
Every job record returned counts once: each item in a search page, feed page or changes batch, and each job detail. Counts, expired ids and the organization list return no job records.
When fewer jobs remain than your limit, the page is shortened to what remains.
When an allowance is used up, requests return 429 until the period resets or you upgrade.

Parameter	Type	Description
Free trial	2/s	500 jobs and 50 requests per week
20k	10/s	20,000 jobs and 10,000 requests per month
50k	10/s	50,000 jobs and 25,000 requests per month
100k	20/s	100,000 jobs and 50,000 requests per month
250k	20/s	250,000 jobs and 125,000 requests per month
500k	30/s	500,000 jobs and 250,000 requests per month

Usage headers

Every metered response includes your current usage:

Parameter	Type	Description
x-plan	string	Your current plan.
x-period-end	timestamp	When the allowance resets.
x-jobs-limit / x-jobs-used / x-jobs-remaining	integer	Jobs in this period.
x-requests-limit / x-requests-used / x-requests-remaining	integer	Requests in this period.

Rate limits

Requests are limited per organization to the steady rate shown above, with short bursts of up to twice that. Over the limit you'll get 429 with a Retry-After header. Use a single worker with backoff rather than many parallel requests.