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:

{
"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

Parameter	Type	Required	Description
`INVALID_API_KEY`	401	No	Missing or invalid X-Api-Key header.
`INVALID_SIGNATURE`	401	No	HMAC-SHA256 signature verification failed.
`TIMESTAMP_EXPIRED`	400	No	X-Timestamp drift exceeds 5 minutes.
`IP_NOT_WHITELISTED`	403	No	Your server IP is not in your whitelist.
`RESELLER_INACTIVE`	403	No	Your reseller account is suspended.
`RATE_LIMIT_EXCEEDED`	429	No	Too many requests for your tier.

Validation Errors

Parameter	Type	Required	Description
`VALIDATION_ERROR`	400	No	Missing required fields or incorrect data types.
`INVALID_CONTENT_TYPE`	415	No	POST requests must use Content-Type: application/json.
`PAYLOAD_TOO_LARGE`	413	No	Request body exceeds maximum size (4KB).
`PAYLOAD_TOO_LARGE`	411	No	POST requests must declare a Content-Length header (no chunked transfer-encoding). Every standard HTTP client sets this automatically for a JSON body.
`INVALID_PAGINATION`	400	No	page must be ≥ 1, limit must be 1-100.
`INVALID_DATE_RANGE`	400	No	Invalid date format or end_date before start_date.
`DATE_RANGE_TOO_LARGE`	400	No	Date range exceeds 90-day maximum.
`INVALID_STATUS_FILTER`	400	No	Invalid status filter value.
`REF_ID_REQUIRED`	400	No	ref_id query parameter is required (order-status).

Order Errors

Parameter	Type	Required	Description
`PRICE_NOT_MATCH`	409	No	Price does not match current system price.
`DUPLICATE_REF_ID`	409	No	An order with this ref_id already exists.
`INSUFFICIENT_BALANCE`	402	No	Not enough balance to place order.
`PRODUCT_NOT_FOUND`	404	No	Invalid or inactive product_code.
`ORDER_FAILED_SUPPLIER_GATE`	503	No	No 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_ID`	400	No	Refused 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_LOCK`	400	No	Refused 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_LIMIT`	400	No	Refused 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_ERROR`	500	No	Unexpected server error. Contact support.

Pre-order 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

Parameter	Type	Required	Description
`GAME_NOT_SUPPORTED`	404	No	The game has no reseller-enabled ID checker.
`VALIDATION_FIELDS_MISSING`	400	No	A required field for this game was not supplied.
`CHECKER_UNAVAILABLE`	503	No	Every validation source was temporarily unreachable, retry shortly.