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:

400Error Response
json
{
"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

ParameterTypeRequiredDescription
INVALID_API_KEY401NoMissing X-Api-Key header, or an invalid key — also returned for a malformed or revoked key.
IP_NOT_WHITELISTED403NoYour server IP is not in your whitelist.
RESELLER_INACTIVE403NoYour reseller account is suspended.
RESELLER_NOT_LINKED403NoYour reseller account has no linked member wallet, so it has no balance to spend. Contact support to have it linked.
MEMBER_NOT_ACTIVE403NoThe member account linked to your reseller is suspended or banned.
RATE_LIMIT_EXCEEDED429NoToo many requests for your tier (GET endpoints and test orders).

Validation Errors

Validation Errors

ParameterTypeRequiredDescription
VALIDATION_ERROR400NoMissing/blank required fields, wrong data types, unknown fields, control characters in an identifier, a malformed category_slug, or a test value other than true / "failed". The message lists every problem found.
INVALID_CONTENT_TYPE415NoPOST requests must use Content-Type: application/json.
PAYLOAD_TOO_LARGE413NoRequest body exceeds maximum size (4KB).
PAYLOAD_TOO_LARGE411NoPOST sent without a Content-Length header. Send the body as a string or buffer (every standard HTTP client sets this automatically) rather than as a stream.
INVALID_PAGINATION400Nopage must be ≥ 1, limit must be 1–100.
INVALID_DATE_RANGE400NoInvalid date format or end_date before start_date.
DATE_RANGE_TOO_LARGE400NoDate range exceeds 90-day maximum.
INVALID_STATUS_FILTER400NoInvalid status filter value.
REF_ID_REQUIRED400Noref_id query parameter is required (order-status).

Order Errors

Order Errors

ParameterTypeRequiredDescription
PRICE_NOT_MATCH409NoPrice does not match current system price.
DUPLICATE_REF_ID409NoAn order with this ref_id already exists.
INSUFFICIENT_BALANCE402NoNot enough balance to place order.
PRODUCT_NOT_FOUND404NoInvalid or inactive product_code — also returned by order-status when no order matches the ref_id (including every test order, which is never stored).
ORDER_FAILED_SUPPLIER_GATE503NoNo supplier could accept the order. Your balance is not deducted. Safe to retry with the SAME ref_id.
INTERNAL_ERROR500NoUnexpected server error. Contact support.

Availability

Availability Errors

ParameterTypeRequiredDescription
MAINTENANCE503NoThe store is in maintenance mode. Nothing was processed and your balance is not deducted. Retry after the number of seconds in the Retry-After header, with the SAME ref_id.

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.

PreviousRate Limits