Rate limits & usage
How the Zenode API throttles requests per minute and how usage is metered for billing across match, data, and AI classes.
Per-minute rate limits
Every response carries standard rate-limit headers, scoped to your key's tier:
1X-RateLimit-Limit: 6002X-RateLimit-Remaining: 5973X-RateLimit-Reset: 1717000000When you exceed the per-minute limit you get a 429 with the error envelope
and a Retry-After header.
Usage is metered per unit of work
Usage is counted per unit of work, not per HTTP request, in three independent classes:
| Class | One unit is… |
|---|---|
| Match requests | one MPN query — /parts/match costs 1; /parts/match/batch with 250 lines costs 250 |
| Part-data / pricing records | one part record returned — a catalog search returning 10 parts costs 10 |
| AI tokens | LLM tokens consumed by AI discovery and deep dive, reported on each job as usage |
Batching is an ergonomic convenience, not a discount: a 250-line batch counts as 250 match requests.
For data endpoints the unit is the part record, so the allowance is effectively a cap on data
returned. X-RateLimit-* headers on a batch response reflect the post-batch remaining count.
AI calls bill by tokens, so every AI job reports a usage object —
{ input_tokens, output_tokens, total_tokens }. For deep dive, each deliverable is metered
separately and usage on the job is the sum.
Check your usage
Read your running total in each class for the current billing period with
GET /v1/usage. The per-minute limits are live on the X-RateLimit-*
headers above; /v1/usage is the per-period view across all three classes.
Next
- Usage — current-period consumption per class
- Async AI jobs — where
usageis reported - Authentication — scopes and tiers