Error Codes

Comprehensive list of API error codes and their meanings.

When an API request fails, it returns a non-2xx HTTP status code and a JSON error response. Every endpoint uses this exact shape: error is always the stable machine-readable code, message is the human-readable detail:

400Error Response
json
{
"success": false,
"error": "INSUFFICIENT_BALANCE",
"message": "You do not have enough balance to place this order.",
"request_id": "a1b2c3d4-e5f6-..."
}

Parsing errors

Branch on the top-level error field (the code), never on HTTP status alone, and never expect a nested error.code. The message is for humans/logs; do not match on its text, as wording may change. The same request_id is also returned in the X-Request-Id response header for support tickets.

Authentication Errors

Auth Errors

ParameterTypeRequiredDescription
INVALID_API_KEY401NoMissing or invalid X-Api-Key header.
INVALID_SIGNATURE401NoHMAC-SHA256 signature verification failed.
TIMESTAMP_EXPIRED400NoX-Timestamp drift exceeds 5 minutes.
IP_NOT_WHITELISTED403NoYour server IP is not in your whitelist.
RESELLER_INACTIVE403NoYour reseller account is suspended.
RATE_LIMIT_EXCEEDED429NoToo many requests for your tier, or 30 failed authentications from your IP in one minute. Wait for the Retry-After seconds.

Validation Errors

Validation Errors

ParameterTypeRequiredDescription
VALIDATION_ERROR400NoMissing required fields or incorrect data types.
INVALID_CONTENT_TYPE415NoPOST requests must use Content-Type: application/json.
PAYLOAD_TOO_LARGE413NoRequest body exceeds maximum size (4KB).
PAYLOAD_TOO_LARGE411NoPOST requests must declare a Content-Length header (no chunked transfer-encoding). Every standard HTTP client sets this automatically for a JSON body.
INVALID_PAGINATION400Nopage must be ≥ 1, limit must be 1-100.
INVALID_DATE_RANGE400NoInvalid date format or end_date before start_date.
DATE_RANGE_TOO_LARGE400NoDate range exceeds 90-day maximum.
INVALID_STATUS_FILTER400NoInvalid status filter value.
REF_ID_REQUIRED400Noref_id query parameter is required (order-status).

Order Errors

Order Errors

ParameterTypeRequiredDescription
PRICE_NOT_MATCH409NoPrice does not match current system price.
DUPLICATE_REF_ID409NoAn order with this ref_id already exists.
INSUFFICIENT_BALANCE402NoNot enough balance to place order.
PRODUCT_NOT_FOUND404NoInvalid or inactive product_code.
ORDER_FAILED_SUPPLIER_GATE503NoNo supplier is currently available for this product. The order was NOT created and your balance was NOT deducted. Safe to retry with the SAME ref_id.
INVALID_ID400NoRefused before charge: the ID checker explicitly confirmed the target account does not exist. NO order is created, no balance moves, and the ref_id stays reusable. Correct the target/zone before retrying; do not auto-retry unchanged.
REGION_LOCK400NoRefused before charge: the target account's verified region cannot receive this product. NO order is created, no balance moves, and the ref_id stays reusable. Not retryable unchanged; check the region with POST /validation.
PURCHASE_LIMIT400NoRefused before charge: the target account already used its purchase allowance for this limit-gated product (first top-up tier or weekly/monthly pass). NO order is created, no balance moves, and the ref_id stays reusable. Not retryable for the same account.
INTERNAL_ERROR500NoUnexpected server error. Contact support.

Pre-charge checks are refunds you never need

INVALID_ID, REGION_LOCK and PURCHASE_LIMIT refuse an order that would have failed after dispatch — instantly, with no balance movement, instead of a debit followed by an automatic refund. They only fire on a definitive checker answer for games with the ID checker enabled; if the checker cannot determine the answer, the order proceeds normally. Calling POST /validation before ordering surfaces the same verdicts up front.

Retrying safely

Always retry with the same ref_id. It is the idempotency key: a retry either resolves to your original order or returns DUPLICATE_REF_ID, never a second charge. Generating a fresh ref_id for a retry is what causes double orders.

Validation Errors

Validation Errors

ParameterTypeRequiredDescription
GAME_NOT_SUPPORTED404NoThe game has no reseller-enabled ID checker.
VALIDATION_FIELDS_MISSING400NoA required field for this game was not supplied.
CHECKER_UNAVAILABLE503NoEvery validation source was temporarily unreachable, retry shortly.

Service Errors

Service Errors

ParameterTypeRequiredDescription
MAINTENANCE503NoThe store is closed for maintenance. Every endpoint, the sandbox included, answers this until it reopens. No order is created and no balance moves. Wait the Retry-After seconds, then retry with the SAME ref_id.

MAINTENANCE: new code (changelog, 2026-10-31)

Additive. Treat it like any 503: back off for the Retry-After seconds and retry. Orders accepted before maintenance began keep processing, and their callbacks are still sent.

PreviousRate Limits