Why OpenFoot API enforces both a monthly quota and a per‑minute limit
A monthly quota caps the total number of requests a plan can consume over a calendar month. For the free Starter plan this is 5,000 requests, and the quota resets on the 1st of each month (UTC). The quota protects the service from excessive long‑term usage and aligns with the pricing tiers described on the /pricing page.
The per‑minute rate limit controls the burst of traffic that any single client can generate. The Starter plan allows 60 requests per minute. This limit guards against short‑term spikes that could degrade response times for other users. Together, the two limits provide predictable capacity planning for both the API provider and the consumer.
Reading the RateLimit response headers
Every successful response from OpenFoot API includes a set of RateLimit headers. The headers convey three pieces of information: the maximum allowed value for the current period, the number of requests remaining in that period, and the time when the count will reset. These values are expressed in the same units as the corresponding limit (monthly or per‑minute).
Clients should parse these headers on each request and store the remaining count and reset timestamp. When the remaining count reaches zero, the client knows that any further request will be rejected with HTTP 429 until the reset time arrives.
Detecting and handling quota exhaustion
When a request exceeds either the monthly quota or the per‑minute limit, the API returns HTTP 429 (Too Many Requests). No overage billing is applied; the request simply fails. The response also includes the RateLimit headers indicating when the limits will be refreshed.
A robust client should treat a 429 as a signal to pause further calls. The client can calculate the wait time from the reset timestamp provided in the headers, sleep for that duration, and then resume making requests. This approach prevents unnecessary retries and respects the API’s usage contract.
Designing a client that respects both limits
The client needs two independent counters: one for the monthly quota and one for the per‑minute window. At startup, the client can read the RateLimit‑Limit header for the month and store the total allowed requests. After each request, it decrements the monthly counter based on the RateLimit‑Remaining header.
For the per‑minute window, the client should maintain a sliding‑window counter or use a token‑bucket algorithm that refills at the rate defined by the per‑minute limit. Before sending a request, the client checks both counters; if either counter indicates no remaining capacity, the client waits until the next reset as indicated by the RateLimit‑Reset header.
Testing and monitoring usage
During development, use the /v1/matches endpoint with a narrow query (e.g., a specific date range) to keep request volume low while validating header handling. The meta.scope.window field shows the default date range when no filters are supplied, helping you avoid accidental large result sets.
Log the RateLimit headers for each request in a monitoring system. By tracking the remaining counts over time you can spot trends that approach the monthly quota early, allowing you to adjust request frequency or upgrade the plan before hitting a hard limit.
Frequently asked questions
What happens if I exceed the monthly quota?
The API returns HTTP 429. No additional charges are applied, and the quota resets on the 1st of the month (UTC).
Can I request a higher limit without changing plans?
Higher limits are tied to plan tiers. To increase either the monthly quota or the per‑minute rate limit you need to upgrade, as indicated by a 403 response with code plan_upgrade_required.
Do the RateLimit headers differentiate between monthly and per‑minute limits?
Yes. The headers include separate values for the total allowed requests for the month and for the minute, each with its own remaining count and reset timestamp.
Sources and further reading
Product descriptions and examples were checked against the OpenFootAPI v1 contract on 1 October 2026.