API requests return permission, validation, or rate-limit errors

Authentication succeeds, but API v2 returns 403, a validation error, 404, 409, 429 rate_limit_exceeded, or 503.

Fix itCopy link to Fix it

1. Record the method, /v2 path, status, and complete error object.
2. Compare the endpoint’s Required scope and feature in the API reference.
3. Validate required fields, allowed enum values, numeric bounds, and content type.
4. Confirm all IDs belong to the authenticated community.
5. For 429, read Retry-After and error details such as limit, remaining, and resetMs when supplied.
6. For 503, record the error code and read Retry-After when supplied.
7. For a write timeout, conflict, or dependency failure, fetch current state before another attempt.

Grant only the missing scope, restore the entitled feature, or correct the request to match the generated schema. Respect Retry-After with bounded backoff and reduce unnecessary polling. A 503 requires the named dependency to recover; rotating credentials or widening scopes will not fix it. Do not hard-code a universal request quota because limits can vary by deployment.

For roblox_cloud_* codes, use the Roblox connection error table. Connection or refresh failures have different recovery steps from invalid Clan Labs API authentication. Inspect current Roblox state before retrying a timed-out rank write.

A 409 medal_limit_reached response means the API's total medal-occurrence limit prevents another award. Repeated medal awards add occurrences, and repeated removals remove another occurrence. Read the member's current medal count before resubmitting either request after an uncertain result; see idempotency and retries.

When to retryCopy link to When to retry

Retry a corrected validation request immediately. For 429 rate_limit_exceeded, wait at least the supplied Retry-After. A 429 queue-full response can omit that header; reduce submissions and retry with bounded exponential backoff. Keep the same Idempotency-Key when retrying asynchronous Roblox submission. Retry safe reads after 503 with bounded backoff. Retry writes only when the endpoint documents idempotent behaviour or after reconciling state.

Still failing?Copy link to Still failing?

Contact Clan Labs support for a reproducible request that matches the current reference but returns an unexplained server or permission error.

Include request method/path, redacted body, status, response error object, response/request correlation header if present, timestamp, key name and scopes, and plan. Never include the API key.