کدهای خطا و وضعیتهای 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 را بخوانید تا ببینید حساب شریک چگونه کار میکند.