Códigos de error y estados HTTP

Todo fallo devuelve un código estable y legible por máquina junto al estado HTTP. Ramifique según el código, nunca según el texto del mensaje: los mensajes están escritos para personas y pueden reescribirse, mientras que los códigos forman parte del contrato.

Los 32 códigos que puede devolver la API para revendedores, agrupados según qué salió mal. Cada entrada indica el estado HTTP con el que llega y el cambio que lo resuelve.

Authentication (401)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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)

Código	HTTP	Qué significa	Cómo resolverlo
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.

¿Recién llega a la plataforma? Empiece por la presentación de la API de recargas de juegos para revendedores, o lea la presentación del programa de revendedores de SHOP2TOPUP para ver cómo funciona la cuenta de socio.