Rate limits and quota

Each plan defines two limits:

• Rate limit — the maximum number of requests per minute.
• Monthly quota — the maximum number of requests per calendar month.

Both are reported in response headers, so your current usage is always visible without waiting for a limit to be reached.

Headers

Header	Description
X-RateLimit-Limit	Requests permitted per minute.
X-RateLimit-Remaining	Requests remaining in the current minute.
X-Quota-Limit	Requests permitted in the current month.
X-Quota-Remaining	Requests remaining in the current month.
X-Quota-Reset	Unix timestamp at which the quota resets.
X-Quota-Period	The billing period the quota headers describe.
Retry-After	Seconds to wait before retrying. Included with 429 responses.

X-Quota-* headers are included when your plan has a monthly quota. Responses rejected during authentication (401, and the 429 for too_many_failed_attempts) do not include limit headers.

Exceeding a limit

Code	Status	Description
rate_limit_exceeded	429	Rate limit reached. Retry after Retry-After seconds.
quota_exceeded	429	Monthly quota reached. Resets at X-Quota-Reset.

Both use status 429; distinguish them by code.

if ($response->status() === 429) {
    if ($response->json('code') === 'rate_limit_exceeded') {
        sleep((int) $response->header('Retry-After'));
        // retry
    }

    // quota_exceeded: wait until X-Quota-Reset
}

Scope

Limits apply per account. Creating additional API keys does not increase them.

What counts towards the quota

Only successful requests count towards your quota. Requests that return an error — invalid parameters, authentication failures, filters outside your plan, or a server error — are not counted.

Recommendations

• Read the limit headers rather than tracking usage client-side.
• Honour Retry-After exactly.
• Request up to 100 results per page rather than issuing more requests with smaller pages.
• When polling, use published_after to fetch only new articles. See Pagination.