Rate limits & quotas

FuelAtlas enforces three independent limits. Understanding which one you hit tells you exactly what to do about it — the error code is always specific.

Your exact numbers depend on your plan. GET /v1/me returns your plan.rate_limit_per_min, monthly plan.monthly_quota by family, and plan.used_this_month — check it rather than hard-coding limits.

#Request rate

Each key gets a requests-per-minute allowance. Responses carry standard rate-limit headers so you can pace yourself before hitting the wall:

RateLimit-Limit: 600
RateLimit-Remaining: 574
RateLimit-Reset: 27

When you exceed it:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/problem+json

{
  "type": "https://www.fuelatlas.com/developers/guides/errors#rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "retry_after": 12
}

Honor retry_after (seconds) — or the RateLimit-Reset header — and retry with exponential backoff plus jitter. Don't retry tighter than the reset window; it just burns more budget.

#Monthly quotas

Quotas are metered per endpoint family (locations, stations, routes, and so on), so heavy location ingestion doesn't starve your station queries. GET /v1/me shows the split. 429 quota_exceeded means a family's monthly allowance is spent — wait for the month to reset, or upgrade in the Developer Console. GET /v1/me itself is quota-exempt, so a maxed-out key can always introspect why.

#Station-query budget

Station disclosures have their own budget on top of quotas, because each disclosed station is a piece of the pricing dataset. Every station returned by GET /v1/stations, POST /v1/stations/along-route, or an autoguide recommendation is charged. See Prices & stations for how to stay well under it (query real corridors, not wide areas). Exhaustion is 429 station_budget_exceeded.

#Handling 429 well

• Read the code, not just the status — rate_limited, quota_exceeded, and station_budget_exceeded need different responses.
• Back off on rate_limited; retrying immediately never helps.
• Don't retry quota_exceeded / station_budget_exceeded in a loop — they won't clear until reset or upgrade. Alert instead.
• Batch writes. One POST /v1/locations with 500 breadcrumbs costs one request; 500 single-item calls cost 500.

#Next

• Errors — the full problem+json envelope and code registry.
• Prices & stations — the station budget in detail.