Rate limits & error codes

Every REST endpoint shares the same authentication model, error format and rate-limit rules. This page is the reference for what happens when a request is refused and how to handle it in a production client.

Rate limits

Endpoints	Limit	Scope
`POST /projects/upload-file`, `POST /projects/distribute-file`	1 request per 2 minutes	Per account
Project control (`enable`, `disable`, `sessions/end`, `active-build`, `settings`)	30 requests per minute, all five combined	Per account
Reads (every `GET` endpoint)	300 requests per minute, API-key callers	Per account
Analytics date windows	At most 92 days between `startDate` and `endDate`, API-key callers	Per request

“No fixed limit” still means you must behave well. Aggressive polling or parallel fan-out against the analytics endpoints can be throttled at the edge. Poll build status every 30 to 60 seconds and live stats every few seconds at most; if you need more, contact support.

When you exceed a limit the API returns 429 Too Many Requests with a Retry-After header (seconds). The read limit and the date-window ceiling apply to API-key callers. They are abuse brakes: 300 reads a minute is far above what an integration needs, and a 92-day window covers any report. To read a longer period, move the window and page through it. A wider window is refused up front with 400 VALIDATION_FAILED naming startDate and maxDays, before anything is queried.

{ "message": "Rate limit exceeded. Try again in 117 seconds." }

{ "code": "RATE_LIMITED", "message": "Too many control calls; at most 30 per minute per account. Retry in 12s.", "retryAfter": 12 }

{ "code": "RATE_LIMITED", "message": "Too many read calls; at most 300 per minute per account. Retry in 4s.", "retryAfter": 4 }

{ "code": "VALIDATION_FAILED", "message": "Date range too wide: at most 92 days between startDate and endDate (requested 240). Move the window to page through longer periods.", "field": "startDate", "maxDays": 92 }

Error response format

Every error is JSON with a human-readable message. Newer endpoints add a stable code you can branch on, and where useful a field naming what was wrong:

{
  "code": "VALIDATION_FAILED",
  "message": "Field(s) not settable here: allowedUsers, region",
  "unknown": ["allowedUsers", "region"]
}

Always read message. Branch on code where present; treat it as optional on the older endpoints. There is no errors[] array or nested envelope.

Stable codes

`code`	Status	Meaning
`API_KEY_IN_QUERY`	`400`	The key was sent in the URL. Move it to the `x-api-key` header and rotate it.
`VALIDATION_FAILED`	`400`	A field is missing, unknown, out of range or inconsistent. The response names it (`field`, `unknown`, `invalid` or `inconsistent`).
`BAD_REQUEST`	`400`	The request could not be understood.
`UNAUTHENTICATED`	`401`	No valid credential.
`API_KEY_SCOPE`	`403`	The key lacks the scope the endpoint needs (`requiredScope`).
`FORBIDDEN`	`403`	Authenticated, but not allowed on this resource.
`NOT_FOUND`	`404`	No such project, build, session or log.
`CONFLICT`	`409`	The action does not fit the resource’s current state, e.g. activating a build that is still processing.
`RATE_LIMITED`	`429`	Over the limit; see `retryAfter` and the `Retry-After` header.
`INTERNAL_ERROR`	`500`	Something failed on our side; safe to retry once.

HTTP status codes

Status	Meaning	Typical example
`200 OK`	Request succeeded with a response body.	Any read; control actions return the resulting state.
`400 Bad Request`	Malformed request or invalid field.	`"maxRunTime must be an integer between 1 and 1440"`
`401 Unauthorized`	Key missing or invalid.	`"Authentication required"`
`403 Forbidden`	Wrong account, insufficient team role, or missing scope.	`"API_KEY_SCOPE"`
`404 Not Found`	The resource does not exist.	`"Build not found on this project"`
`409 Conflict`	Wrong state for the action.	Build still `Extracting & Scanning`.
`415 Unsupported Media Type`	`Content-Type` is not `application/json` on a body request.
`429 Too Many Requests`	Rate limit.	See above.
`500 Internal Server Error`	Unexpected failure.	`"Something went wrong on our side."`

Common causes

Required field omitted (fileUrl, projectId, buildId).
Wrong type or out-of-range value; enums are case-sensitive (H264, not h264).
A settings field that is not on the allow-list, such as region or allowedUsers.
Cross-field conflict: minBitrate above the stored maxBitrate, odd resX.
Webhook URL pointing at a private address.

x-api-key header missing.
Key rotated or revoked.
Key from a different environment.

Key issued without the scope (API_KEY_SCOPE).
Project belongs to another account, or the session id does not belong to the given projectId.
Team role cannot edit projects (control endpoints) or upload builds.

projectId, buildId, sessionId or logFileId does not exist.
The session has no Unreal log (its application never started, or it is still running).

Retry strategy

Retry on 429 (after Retry-After or the seconds in the message) and on 5xx, with exponential backoff and jitter.
Do not retry other 4xx responses; the request is wrong and retrying will not fix it.
Control actions are idempotent: repeating enable, disable or sessions/end after a timeout is safe. Repeating active-build re-queues distribution, which is harmless but wasteful. Repeating PATCH /settings with the same body is safe.

Getting started

Projects

Builds

Project control

Sessions & analytics

Webhooks

Integrations

Rate limits & error codes

Rate limits

Error response format

Stable codes

HTTP status codes

Common causes

Retry strategy

​Rate limits

​Error response format

​Stable codes

​HTTP status codes

​Common causes

​Retry strategy

Rate limits

Error response format

Stable codes

HTTP status codes

Common causes

Retry strategy