Errors and rate limits

The error format

Every error from the Developer API has the same shape:

{
    "error": {
        "code": "insufficient_scope",
        "message": "This token is missing the events:read scope.",
        "required_scope": "events:read"
    }
}

code is stable, so match on it. message is for people and may change. Some codes add fields next to them, such as required_scope above or fields on a validation error.

Status	Code	Meaning
401	unauthenticated	No token, or the token is unknown, expired or revoked.
409	limit_reached	An app already has the most webhooks it may register for this creator.
403	insufficient_scope	The token lacks the scope named in required_scope.
403	forbidden	The token may not do this, such as subscribing to another creator's channel, or an app token calling a creator endpoint.
403	feature_unavailable	The endpoint belongs to a product that is not enabled for the account, such as Gleem IRL or OBS Server Hosting.
404	pairing_not_found	No IRL Sidekick is waiting to be paired with this code. It expired or was answered already.
409	device_offline	The IRL device is offline, so the command was not sent. Commands are never queued.
404	not_found	No such endpoint or resource.
422	validation_failed	The request was malformed. fields lists the problems per field.
429	rate_limited	Too many requests. Wait for the number of seconds in Retry-After.
5xx	server_error	Something broke on our side. Retry later.

For an OAuth access token with a good signature, a 401 also says why in the WWW-Authenticate header: error_description="expired" means refresh and retry, "revoked" means ask the creator to connect again. See OAuth apps.

The OAuth endpoints under /oauth answer in the standard OAuth shape instead, {"error": "invalid_grant", "error_description": "…"} (RFC 6749 § 5.2).

Rate limits

Each token may make 120 requests a minute. The limit counts per token, not per address, so tools sharing a network do not share an allowance. An OAuth app's limit counts per creator it is connected to, across all its installs.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit, the API answers 429 with a Retry-After header.

Events over the WebSocket do not count against the limit. Only the HTTP requests do, including channel authorisation.