Error codes and HTTP statuses

Every failure returns a stable machine-readable code alongside the HTTP status. Branch on the code, never on the message text: messages are written for humans and may be reworded, while codes are part of the contract.

All 32 codes the reseller API can return, grouped by what went wrong. Every entry names the HTTP status it arrives with and the change that resolves it.

Authentication (401)

Code	HTTP	What it means	How to fix it
MISSING_API_KEY	401	API key is requiredNo Authorization header was provided, or the header format is incorrect.	Include the header: Authorization: Bearer <keyId>.<secret>
INVALID_API_KEY	401	Invalid API keyThe provided API key does not match any active key in the system.	Verify your key ID and secret are correct. Regenerate the key from the API Access panel if needed.

Authorization (403)

Code	HTTP	What it means	How to fix it
ACCOUNT_DISABLED	403	Account is disabledYour account has been disabled by an administrator.	Contact support to re-enable your account.
ACCOUNT_FROZEN	403	Account is frozenYour account has been temporarily frozen, usually due to suspicious activity.	Contact support to unfreeze your account.
IP_NOT_ALLOWED	403	IP address not in allowlistThe request originated from an IP address not in your API key allowlist.	Add your server IP to the allowlist in the API Access panel, or remove IP restrictions.

Request validation (400)

Code	HTTP	What it means	How to fix it
MISSING_REQUIRED_FIELD	400	Missing required fieldA required field is missing from the request body.	Check the endpoint documentation for required fields.
INVALID_UUID_FORMAT	400	Invalid UUID formatThe order_id is not a valid UUID format.	Use any valid UUID format (v1, v4, v7, etc). Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
INVALID_QUANTITY	400	Invalid quantityQuantity must be a positive integer.	Provide a quantity >= 1 as an integer.
INVALID_CATEGORY_ID	400	Invalid category IDThe provided categoryId is not a valid number.	Use the Catalog Explorer or GET /catalog/categories to find valid category IDs.
INVALID_BIG_CATEGORY_ID	400	Invalid big category IDThe provided bigCategoryId is not a valid number.	Use the Catalog Explorer or GET /catalog/big-categories to find valid big category IDs.
INVALID_ITEM_ID	400	Invalid item IDThe provided item ID is not valid.	Use the Catalog Explorer or GET /catalog/subcategories to find valid item IDs.
INVALID_SUBCATEGORY	400	Invalid subcategoryThe subcategory ID does not exist or is invalid.	Verify the sub_category_id using the catalog endpoints.
INVALID_PRODUCT_CONFIG	400	Invalid product configurationThe product requirements (player_id, zone_id, etc.) do not match the expected configuration.	Check the subcategory requirements field to see which fields are needed.
INVALID_PAGINATION	400	Invalid pagination parametersPage or limit values are out of range.	Use page >= 1 and limit between 1 and 100.
INVALID_DATE_FORMAT	400	Invalid date formatThe created_after or created_before parameter is not a valid ISO 8601 date.	Use ISO 8601 format: 2024-01-01T00:00:00Z.

Player validation (400)

Code	HTTP	What it means	How to fix it
PLAYER_NOT_FOUND	400	Player not foundThe player ID could not be found in the game system.	Verify the player ID is correct. Check if a zone_id is required for the game.
PLAYER_VALIDATION_FAILED	400	Player validation failedThe game server could not validate the player. This may be a temporary issue.	Retry after a moment. If persistent, verify the player ID and zone.
REGION_MISMATCH	400	Region mismatchThe player belongs to a different region than expected.	Use the correct zone_id or genshin_zone for the player region.

Business rules (400 / 409)

Code	HTTP	What it means	How to fix it
INSUFFICIENT_BALANCE	400	Insufficient wallet balanceYour wallet does not have enough funds to complete this order.	Top up your wallet from the Reload page before placing the order.
OUT_OF_STOCK	400	Product is out of stockThe requested product is currently unavailable.	Try again later or choose a different product.
DUPLICATE_ORDER	409	Duplicate order IDAn order with this UUID already exists. This is an idempotency protection.	Generate a new UUID for a new order. If retrying, use the same UUID to get the existing order.
PRICE_INCREASED	400	Price has increased beyond expectedThe current unit price is higher than the expected_unit_price you provided.	Fetch the latest price with GET /catalog/subcategory/:id/price and update expected_unit_price.
SUBCATEGORY_DISABLED	400	Subcategory is disabledThis product has been temporarily disabled.	Choose a different product or try again later.

Not found (404)

Code	HTTP	What it means	How to fix it
ORDER_NOT_FOUND	404	Order not foundNo order exists with the given order ID.	Verify the order ID is correct.
ITEM_NOT_FOUND	404	Item not foundThe requested catalog item does not exist.	Use the catalog endpoints to find valid item IDs.
ITEM_NOT_AVAILABLE	404	Item not availableThe item exists but is not currently available for purchase.	Try again later or choose a different item.

Batch request validation (400)

Code	HTTP	What it means	How to fix it
INVALID_ORDER_IDS_FORMAT	400	Invalid order_ids formatThe order_ids field must be an array of strings.	Provide order_ids as: { "order_ids": ["uuid1", "uuid2"] }.
EMPTY_ORDER_IDS	400	Empty order_ids arrayThe order_ids array cannot be empty.	Provide at least one order ID in the array.
TOO_MANY_ORDER_IDS	400	Too many order IDsMaximum 50 order IDs can be queried at once.	Split your request into batches of 50 or fewer.

Rate limiting (429)

Code	HTTP	What it means	How to fix it
RATE_LIMIT_EXCEEDED	429	Rate limit exceededYou have exceeded the rate limit for this endpoint. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. When exceeded, the 429 response body contains: limit, remaining (0), retry_after (seconds to wait), and window_seconds. A Retry-After header is also set.	Wait for the number of seconds indicated by retry_after or the Retry-After header before retrying. Monitor X-RateLimit-Remaining headers to avoid hitting limits.

Server side (5xx)

Code	HTTP	What it means	How to fix it
INTERNAL_ERROR	500	Internal server errorAn unexpected error occurred on the server.	Retry the request. If persistent, contact support.
SERVICE_UNAVAILABLE	503	Service temporarily unavailableThe service is temporarily down for maintenance or overloaded.	Wait and retry after a few minutes.

New to the platform? Start with the game top-up API overview for resellers, or read the SHOP2TOPUP reseller programme overview for how the partner account works.