Errors and rate limits

API v2 returns machine-readable errors in one envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "body/userId must be integer",
    "details": {
      "issues": [
        {
          "instancePath": "/userId",
          "keyword": "type",
          "message": "must be integer"
        }
      ]
    }
  }
}

Branch application logic on error.code, not on human-readable message. The wording can improve without changing the condition. details is optional and varies by error.

Status codesCopy link to Status codes

Roblox dependency failures can return 502 Bad Gateway for an unavailable or rejected upstream connection and 504 Gateway Timeout for a timed-out request. Reconcile the resource before retrying a write.

Each generated endpoint page lists the responses declared by its route schema. Runtime dependency failures can also return 502, 503, or 504 even when that status is not listed on the individual page.

Important error codesCopy link to Important error codes

Authentication and entitlement codes include missing_credentials, unauthorized, api_disabled, key_disabled, legacy_key_unsupported, insufficient_scope, entitlement_required, api_access_unavailable, and feature_unavailable. Routing and validation can return route_not_found and validation_failed. Dependency failures can return dependency_unavailable or a more specific code such as data_rights_unavailable.

An insufficient_scope response also sets WWW-Authenticate with the required scope and includes required and granted scopes in details.

Roblox connection and medal errorsCopy link to Roblox connection and medal errors

These codes apply to Roblox-backed operations or medal changes, as appropriate. Roblox authorization is separate from the Clan Labs API key supplied by your integration.

Always honor the actual response's retry interval. A Roblox rate-limit response is distinct from the API key's request budget and need not contain its limit, remaining, or resetMs details.

Rotating a working Clan Labs API key does not reconnect Roblox. See Roblox connection recovery and medal retry behavior.

Roblox operation outcomesCopy link to Roblox operation outcomes

When shared Roblox scheduling is enabled, synchronous rank and suspension routes, member refreshes that run AutoRank, experience writes, and event finishing can return these outcomes. Experience changes, finished events, and their awards may already be committed when a Roblox rank outcome is pending; check the operation status before repeating those writes.

Existing synchronous success responses still mean the rank change is confirmed or the current rank already matches. The separate asynchronous endpoint returns 202 for acceptance. Its submit, read, and cancellation resources advertise these availability codes:

See Roblox operations for polling and cancellation.

Rate limitingCopy link to Rate limiting

Rate limits protect both unauthenticated traffic and authenticated keys. The values are deployment-configurable, so clients must not assume a fixed number from old examples.

A limited response uses 429 rate_limit_exceeded, sets Retry-After in seconds, and includes values such as:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too Many Requests",
    "details": {
      "limit": 100,
      "remaining": 0,
      "resetMs": 30000
    }
  }
}

The numbers above illustrate the shape only. Always use the values in the actual response.

For rate_limit_exceeded, wait at least the supplied Retry-After, add jitter when many workers share a key, reduce polling, and avoid retry storms. For scheduler queue-full, the header can be absent: reduce submissions and retry with bounded exponential backoff. When submitting to POST /v2/roblox-operations/ranks, reuse the same Idempotency-Key for the same intent. Synchronous routes do not accept that header: check the current resource and any returned operation status before repeating the route's write. Experience changes, event awards, and other local effects may already be committed; follow that route's retry guidance. A 429 does not justify rotating keys.

For 503, use Retry-After when the response supplies it. Retry safe reads with bounded backoff. Before retrying a write, fetch the current resource and determine whether the first attempt changed it.

For a diagnostic checklist, see API request errors.