Rate limits

Limits are counted in units per minute (fixed 60-second windows). Each request spends its operation cost in two buckets at once — its connection and your app — and is allowed only when both have room. A request rejected by one bucket is refunded in the other.

Two groups of buckets

• Read — every GET, POST /v1/connection/sync and the webhook settings routes. Defaults: 60 units / min per connection, 1,000 per app, 1,000 for all personal access tokens of one user.
• Commands — every write (vehicle commands and booking writes). Defaults: 30 units / min per connection, 300 per app, 300 for all personal access tokens of one user. A command never spends read units and a read never spends command units.
• Most operations cost 1 unit; history and list endpoints (locations, trips, bookings, notifications, diagnostics, trip route) cost 3; syncConnection and the connection webhook updates cost 10. The OpenAPI document publishes each cost as x-fleetbold-rate-cost and its group as x-fleetbold-rate-bucket.
• POST /v1/connection/sync is also limited to once per 60 seconds per connection.

Your app's policy

The numbers above are FleetBold's default rate policy. FleetBold can move an app to a preset (default, elevated: 300 / 5,000 reads per minute, high: 1,200 / 20,000) or change individual values for it. Your effective limits are in the app Overview → Rate limits card (read-only). Ask FleetBold support when your usage needs more; a change applies to every token of the app within seconds, no new token needed.

Headers

Every authenticated response carries the state of the tighter bucket of the group it was charged to: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window ends). A vehicle command describes the commands bucket (for example X-RateLimit-Limit: 30).

429 and Retry-After

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23

{"error":{"type":"rate_limited","code":"rate_limited","message":"Rate limit exceeded for this connection","retry_after_seconds":23,"request_id":"req_…"}}

• Wait Retry-After seconds before the next call. Never retry in a tight loop: the rejecting bucket stays charged.
• The message names the bucket (this connection, this app, your personal access tokens); command buckets say Command rate limit exceeded for ….
• Vehicle commands can also answer 429 command_loop_suspected (a cool-down of one command on one vehicle) or 429 command_loop_blocked (every command of that connection to that vehicle). Both carry Retry-After; see the Vehicle commands guide, "Loop protection".
• 409 vehicle_command_in_flight (with Retry-After) means another command for the same vehicle is still queued or being sent on this connection.

When FleetBold's rate-limit store is unavailable

Rate-limited paths fail closed: instead of running unmetered they answer 503 service_unavailable with reason: redis_unavailable and Retry-After: 5. Retry with backoff. POST /oauth/token and /userinfo answer the protocol form 503 {"error":"temporarily_unavailable"}.

Token endpoint

POST /oauth/token limits failed attempts only (invalid_client / invalid_grant): 20 per 5 minutes per client and IP address, 100 per 5 minutes per IP address. A burst of invalid_grant usually means you refresh with a rotated refresh token: store the new one after every refresh.

Staying inside the budget

• Page with limit=200 instead of many small pages; cache /v1/vehicles and /v1/organizations, which change rarely.
• Poll GET /v1/commands/{command_id} (a read) with the Retry-After it returns instead of re-sending a command.
• Spread per-user jobs over the minute instead of firing them all at :00.