429, check its reason and Retry-After before sending another request.
Account allowances
A batch can contain up to 25 items, so a full minute of full batches fits both minute allowances: 100 batches on Pro, or 400 on Max. You still need to handle either limit, including near a window boundary.
A server error (
500 or above) does not count toward the monthly quota or toward daily_usage.used. The quota counter can keep up to 2,000 server errors that were already counted before this rule, until the UTC month resets. A server error after the rule is left out of the counter and of the usage invoice.
Monthly quota and pay as you go
Enable pay as you go on Developers if you need more than your plan’s included requests. It is off by default.
Read the account’s returned
ceiling instead of assuming a limit from its plan name. If unavailable_reason is usage_price_reconciliation_required, billing needs reconciliation: pay_as_you_go is false and additional requests cannot be billed. Open Billing or contact support; repeated requests do not repair that setting.
A quota error’s Retry-After and error.retry_at identify the next monthly reset. Repeated short retries cannot clear it; enable pay as you go, arrange a higher ceiling when needed, or schedule the next request for the reset.
Check usage
GET /api/v1/usage returns monthly_quota without spending the normal request allowance:
Response headers
These illustrative headers, from a Pro key, describe the request and monthly allowances.RateLimit-Limit and X-RateLimit-Limit report your plan’s minute allowance: 100 on Pro, 400 on Max.
A batch adds
X-Request-Cost for its item count and X-Batch-RateLimit-Limit, X-Batch-RateLimit-Remaining, and X-Batch-RateLimit-Reset for its item allowance. Browser JavaScript can read these headers.
X-Request-Id also appears on errors, timeouts, and 304 responses. Supplying your own header of the same name does not choose the response ID.
Special limits
On a
401 or 402, RateLimit-* describes the IP allowance, rather than the account’s request allowance. An exhausted IP allowance produces reason ip_rate_limited; sustained excess traffic can produce ip_throttled with a longer cooldown.
Handle a 429
This example makes at most 3 attempts and waits at most 60 seconds between attempts. Longer delays are returned to the caller for scheduling:
Reduce repeated reads
- Use the largest supported page size and follow pagination.
- Batch up to 25 wallet or market lookups in one request.
- Share polling work across processes that use the same account.
- Reuse
ETagvalues withIf-None-Matchwhere supported. A304saves the response body but still counts as 1 request.
Endpoints with ETags
The current endpoints withETag support are:
Limits
The default Edge Hunter board, reports, search, event replay, streams, usage, account identity, exports, and webhooks do not return anETag. Both advanced Edge Hunter views use Cache-Control: private, no-cache; revalidate before reusing a stored response. The sandbox does not use an account quota and contains no production data.