GW Ultimate API
Docs
Docs/Operations/Errors & rate limits

Errors & rate limits

Bodies are JSON. Use HTTP status; most errors also have error and code when they apply.

Rate limits

Rate limits apply to your user account. Two rolling windows (1 second and 1 minute).

1 second (rolling)

40

Up to 40 calls per second

1 minute (rolling)

200

Up to 200 calls per minute

Counts toward all listed routes in the reference. When over the limit, 429 and: 

{
  "success": false,
  "code": "RATE_LIMIT",
  "error": "TOO MANY REQUESTS"
}

May also send Retry-After (seconds). Rarely, rate limit checks return 503 and RATE_LIMIT_UNAVAILABLE.

Auth & access

HTTP code (if any) When
401 MISSING_API_KEY No X-API-Key or Bearer token.
401 INVALID_API_KEY_FORMAT / INVALID_API_KEY Malformed or unknown key.
403 API_DISABLED API not turned on for your account in Telegram.
403 API_DISABLED_BY_ADMIN Access turned off for your account.
403 API_NOT_ELIGIBLE Account doesn’t meet the rules for using the API yet, if that rule is on.
403 ACCOUNT_BANNED Account blocked.
403 ACCOUNT_RESTRICTED Account temporarily limited.
403 IP_ALLOWLIST_REQUIRED Only listed IPv4 addresses may call the API. Add an IPv4 in Telegram (Profile → API access → IP address config).
403 IP_NOT_ALLOWED IP not allowed for this account.
401 — Invalid JSON body with INVALID JSON (malformed body pipeline).

Orders & validation

HTTP Typical error / code When
400 INVALID BODY Schema validation failed (missing fields, wrong types).
400 INVALID REQUEST Missing pid / userId / zoneId / serverId / trxid as required for the line.
400 UNKNOWN PID pid does not match any active catalog GWPID.
400 GAME DISABLED Service exists but is not orderable on this line.
400 code: INVALID_PRODUCT / PRODUCT_DISABLED Product inactive for orders.
400 QUANTITY ONLY FOR GAMEKEY OR GIFTCARD quantity was sent for a top-up / non-stock line.
400 QUANTITY EXCEEDS MAX / QUANTITY_EXCEEDS_MAX Gamekey/giftcard quantity over 500. Order is rejected completely (no silent cap).
403 FORBIDDEN That trxid is already tied to a different account.
429 DUPLICATE_IN_FLIGHT Same trxid is already being processed (in-flight lock).
400 INSUFFICIENT BALANCE Wallet cannot cover the order. Top up in Telegram (no add-balance API).
400 various (insufficient stock, etc.) Gamekey/gift card or game-specific order placement failures.
404 ORDER NOT FOUND GET /orders/:id for unknown or other user’s id.
501 NOT IMPLEMENTED Path not available on this build.

Service-wide API_ORDER_DISABLED is in the next table.

Service-wide flags

HTTP code When
503 MAINTENANCE Orders paused for maintenance. Try again later.
503 API_ORDER_DISABLED Orders are off for everyone for a while. GET may still work.
Previous ← Reference
GW Ultimate