Errors & rate limits

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

Rate limits

Each key has its own two rolling limits (1s and 1 minute). They don’t mix with other people’s keys.

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	Finish the IP list for this key in Telegram, then call again.
403	IP_NOT_ALLOWED	IP not allowed for this key.
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.
403	FORBIDDEN	That trxid is already tied to a different key.
429	DUPLICATE_IN_FLIGHT	Same trxid is already being processed (in-flight lock).
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.

Best practices

1. Switch on code in your app; show error in the UI if you have one.
2. On 429, wait for Retry-After if it’s there.
3. On 503 MAINTENANCE, don’t spam new orders — try again later.