Errors & limits

Never retry unchanged — fix the request. Retrying wastes your rate limit.

• missing client_id or return_to·client_id is absent, non-numeric, or <= 0, or return_to is empty.(GET /api/partner/connect)
• invalid return_to·return_to does not parse as a URL.(GET /api/partner/connect)
• invalid request·The body was not form data (`multipart/form-data` or `application/x-www-form-urlencoded`).(POST /api/partner/connect)
• missing client_id or return_to·Same validation as the GET.(POST /api/partner/connect)
• invalid return_to·return_to does not parse as a URL.(POST /api/partner/connect)
• bad_params·client_id missing/non-positive, or return_to missing or unparseable.(GET /api/partner/connect/info)
• bad_json·The request body was not parseable JSON.(POST /api/partner/v1/token)
• code_required·`code` was absent, empty, or not a string.(POST /api/partner/v1/token)
• bad_json·The body was not parseable JSON.(POST /api/partner/v1/verify)
• task_id_and_identity_token_required·Either field is missing, empty, or not a string.(POST /api/partner/v1/verify)
• invalid_slug·The slug is missing, too short or long, or contains anything outside a-z0-9, dash and underscore.(POST /api/partner/v1/tasks/custom)
• invalid_label·The label is empty or longer than 120 characters.(POST /api/partner/v1/tasks/custom)
• invalid_points·Points are missing, non-numeric, zero or negative.(POST /api/partner/v1/tasks/custom)
• points_too_high·Points exceed the per-task ceiling of 1000.(POST /api/partner/v1/tasks/custom)
• bad_json·The body was not valid JSON.(POST /api/partner/v1/tasks/custom)
• slug_contest_id_and_identity_token_required·Any of the three is missing, or contest_id is not a positive integer.(POST /api/partner/v1/award)
• bad_json·The body was not valid JSON.(POST /api/partner/v1/award)
• task_disabled·The task exists but you have disabled it.(POST /api/partner/v1/award)
• award_failed·The write failed and was rolled back. Nothing was recorded; retrying is safe.(POST /api/partner/v1/award)

Do not retry. Either the key is missing, malformed, revoked, or the identity token is stale — mint a new one.

• sign in to grabs.gg first·No valid grabs session cookie on the request.(POST /api/partner/connect)
• invalid_or_revoked_key·No Bearer header at all, a malformed one, an unknown client id, a wrong secret, or a revoked client — this route cannot tell you which.(POST /api/partner/v1/token)
• invalid_or_expired_code·The code was tampered with, has expired (~90s), was issued to a different client, or has ALREADY been exchanged. All four collapse to this one answer.(POST /api/partner/v1/token)
• missing_bearer_key·No `Authorization` header, or one that is not `Bearer <key>`.(GET /api/partner/v1/contests)
• invalid_or_revoked_key·The key parsed but did not resolve to an active client: unknown client id, wrong secret half, a revoked client — or the partner tables are missing entirely. All four are indistinguishable by design.(GET /api/partner/v1/contests)
• missing_bearer_key·No `Authorization` header, or one that is not `Bearer <key>`.(GET /api/partner/v1/contests/{id})
• invalid_or_revoked_key·The key parsed but did not resolve to an active client: unknown client id, wrong secret half, a revoked client — or the partner tables are missing entirely. All four are indistinguishable by design.(GET /api/partner/v1/contests/{id})
• missing_bearer_key·No `Authorization` header, or one that is not `Bearer <key>`.(GET /api/partner/v1/tasks)
• invalid_or_revoked_key·The key parsed but did not resolve to an active client: unknown client id, wrong secret half, a revoked client — or the partner tables are missing entirely. All four are indistinguishable by design.(GET /api/partner/v1/tasks)
• missing_bearer_key·No `Authorization` header, or one that is not `Bearer <key>`.(POST /api/partner/v1/verify)
• invalid_or_revoked_key·The key parsed but did not resolve to an active client: unknown client id, wrong secret half, a revoked client — or the partner tables are missing entirely. All four are indistinguishable by design.(POST /api/partner/v1/verify)
• invalid_identity_token·The token expired (>15 min), was tampered with, or was issued to a DIFFERENT client. Indistinguishable on purpose.(POST /api/partner/v1/verify)
• invalid_or_revoked_key·The key is unknown or revoked.(POST /api/partner/v1/tasks/custom)
• invalid_identity_token·The token is malformed, expired, or was issued to a different partner.(POST /api/partner/v1/award)

Do not retry. The credential is valid but not for this.

• return_to is not allow-listed for this client·The URL parsed, but its origin is not in your allowed_origins. Ask a grabs admin to add it — you cannot.(GET /api/partner/connect)
• Cross-site request blocked·The POST did not come from grabs.gg itself.(POST /api/partner/connect)
• return_to is not allow-listed for this client·Origin not in allowed_origins.(POST /api/partner/connect)
• return_to_not_allowed·The link names a real partner but points at an origin that partner never registered. Deliberately distinct from unknown_client — this is the tampered-link case.(GET /api/partner/connect/info)
• insufficient_scope·The key is valid but was not provisioned with `read`.(GET /api/partner/v1/contests)
• insufficient_scope·The key is valid but lacks `read`.(GET /api/partner/v1/contests/{id})
• insufficient_scope·The key is valid but lacks `read`.(GET /api/partner/v1/tasks)
• insufficient_scope·The key is valid but lacks `verify`.(POST /api/partner/v1/verify)
• insufficient_scope·The key lacks the verify scope.(POST /api/partner/v1/tasks/custom)
• contest_not_yours·That contest is not bound to your account. This is the authorisation boundary — no key can award into a contest it does not own.(POST /api/partner/v1/award)
• member_not_eligible·The member is banned from contests platform-wide.(POST /api/partner/v1/award)

Do not retry. Re-read the catalog; the id may have ended.

• unknown or revoked client·No active partner_clients row for that client_id.(GET /api/partner/connect)
• unknown or revoked client·No active client for that id.(POST /api/partner/connect)
• unknown_client·No active client with that id.(GET /api/partner/connect/info)
• not_found·No contest with that id — OR the underlying contest query failed. A DB blip degrades to 404 here rather than 500.(GET /api/partner/v1/contests/{id})
• unknown_task·A status toggle named a slug you have not declared.(POST /api/partner/v1/tasks/custom)
• unknown_task·You have not declared a task with that slug.(POST /api/partner/v1/award)

Do not retry. Typically a task that is not portable inside a contest — read the task's portable flag first.

• not_portable·The task is not server-verifiable in the derived context. The body also carries `message: "This task type can only be completed in the Telegram bot."`(POST /api/partner/v1/verify)

Do not retry. Trim the request body.

• image_too_large·`extra.image_base64` is longer than 8,000,000 characters.(POST /api/partner/v1/verify)

Retry AFTER the Retry-After header. Polling faster gains you nothing.

• rate limited — try again shortly·The per-IP connect bucket filled.(GET /api/partner/connect)
• rate limited — try again shortly·The per-IP connect bucket filled.(POST /api/partner/connect)
• rate_limited·Per-IP info bucket filled. This response also carries a `Retry-After` header.(GET /api/partner/connect/info)
• rate_limited·Any of the buckets described under `rateLimit` filled. The body carries `retryAfterSeconds`; only the pre-auth buckets also set a `Retry-After` header.(POST /api/partner/v1/token)
• rate_limited·Any of the buckets described under `rateLimit` filled. The body carries `retryAfterSeconds`; only the pre-auth buckets also set a `Retry-After` header.(GET /api/partner/v1/contests)
• rate_limited·Any of the buckets described under `rateLimit` filled. The body carries `retryAfterSeconds`; only the pre-auth buckets also set a `Retry-After` header.(GET /api/partner/v1/contests/{id})
• rate_limited·Any of the buckets described under `rateLimit` filled. The body carries `retryAfterSeconds`; only the pre-auth buckets also set a `Retry-After` header.(GET /api/partner/v1/tasks)
• rate_limited·Any of the buckets described under `rateLimit` filled. The body carries `retryAfterSeconds`; only the pre-auth buckets also set a `Retry-After` header.(POST /api/partner/v1/verify)
• rate_limited·Your per-minute limit is exhausted.(POST /api/partner/v1/tasks/custom)
• rate_limited·Your per-minute limit is exhausted.(POST /api/partner/v1/award)

Safe to retry with backoff.

• internal_error·An unhandled exception inside the handler. Retry; if it persists it is a grabs-side configuration problem, not a bad request.(POST /api/partner/v1/token)
• internal_error·An unhandled exception inside the handler. Retry; if it persists it is a grabs-side configuration problem, not a bad request.(GET /api/partner/v1/contests)
• internal_error·An unhandled exception inside the handler. Retry; if it persists it is a grabs-side configuration problem, not a bad request.(GET /api/partner/v1/contests/{id})
• internal_error·An unhandled exception inside the handler. Retry; if it persists it is a grabs-side configuration problem, not a bad request.(GET /api/partner/v1/tasks)
• internal_error·An unhandled exception inside the handler. Retry; if it persists it is a grabs-side configuration problem, not a bad request.(POST /api/partner/v1/verify)