Rate Limits & Errors

Platform-wide rate limits, throttling behavior, and the error response shapes returned by the ROLLER Platform API.

Rate limits

Surface	Limit	Keyed by	Cooldown when exceeded
REST API	600 requests / minute	IP address	60 seconds
Data API (`/data/`, `/reporting/`)	120 requests / minute	Venue	60 seconds
`POST /token`	60 requests / minute	IP address	5 minutes
`POST /reporting/bulk`	1 request per data set	Venue + export type	~6 hours
`POST /reporting/bulk/revenue-activity`	Burst-limited	Venue	24 hours

When a limit is exceeded the API returns:

HTTP 429 Too Many Requests
Retry-After: 60

Too many requests

Honor the Retry-After header before retrying. Because token requests are tightly limited, cache your access token (valid up to 24 hours) rather than requesting one per call.

📘
During maintenance windows the Data API may return 503 Service Unavailable with the message "We're currently doing some maintenance, please try again later." Build retry-with-backoff into reporting jobs.

Error responses

Status	When	Body shape
`400 Bad Request`	Invalid parameters, dates, or model validation	`{ "Message": "<detail>" }` or ASP.NET model-state dictionary
`403 Forbidden`	Missing/invalid scope, disabled key, decommissioned venue, staff API not enabled	`{ "Message": "Invalid scope" }` or empty/plain-text body
`404 Not Found`	Entity doesn't exist for your authorised venue	Empty body
`409 Conflict`	Business-rule validation failed	`{ "errors": [ { "name": "...", "message": "..." } ] }`
`429 Too Many Requests`	Rate limit exceeded	Plain text `Too many requests` + `Retry-After` header
`503 Service Unavailable`	Reporting maintenance	Plain text message

Practical guidance

Treat 403 with Invalid scope as a configuration problem — verify your key's scoped permissions, don't retry.
Treat 409 payloads as user-correctable validation results; surface the message values.
Retry 429/503 with exponential backoff starting from the Retry-After value.
All endpoints operate on the venue resolved from your bearer token — there is no venue ID parameter. Use one token per venue.

Updated about 1 month ago

Did this page help you?