Коды ошибок и HTTP-статусы
Каждый отказ возвращает стабильный машиночитаемый код рядом с HTTP-статусом. Ветвитесь по коду, а не по тексту сообщения: сообщения написаны для людей и могут быть переформулированы, а коды — часть контракта.
Все коды (32), которые может вернуть реселлерский API, сгруппированы по типу сбоя. У каждой записи указан HTTP-статус, с которым она приходит, и изменение, которое её снимает.
Authentication (401)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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)
| Код | HTTP | Что означает | Как исправить |
|---|---|---|---|
| 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. |
Впервые на платформе? Начните с обзора API пополнения игр для реселлеров, а затем прочитайте обзор реселлерской программы SHOP2TOPUP, чтобы понять, как устроен партнёрский аккаунт.