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:
{
"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
| Parameter | Type | Required | Description |
|---|---|---|---|
INVALID_API_KEY | 401 | No | Missing X-Api-Key header, or an invalid key — also returned for a malformed or revoked key. |
IP_NOT_WHITELISTED | 403 | No | Your server IP is not in your whitelist. |
RESELLER_INACTIVE | 403 | No | Your reseller account is suspended. |
RESELLER_NOT_LINKED | 403 | No | Your reseller account has no linked member wallet, so it has no balance to spend. Contact support to have it linked. |
MEMBER_NOT_ACTIVE | 403 | No | The member account linked to your reseller is suspended or banned. |
RATE_LIMIT_EXCEEDED | 429 | No | Too many requests for your tier (GET endpoints and test orders). |
Validation Errors
Validation Errors
| Parameter | Type | Required | Description |
|---|---|---|---|
VALIDATION_ERROR | 400 | No | Missing/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_TYPE | 415 | No | POST requests must use Content-Type: application/json. |
PAYLOAD_TOO_LARGE | 413 | No | Request body exceeds maximum size (4KB). |
PAYLOAD_TOO_LARGE | 411 | No | POST 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_PAGINATION | 400 | No | page must be ≥ 1, limit must be 1–100. |
INVALID_DATE_RANGE | 400 | No | Invalid date format or end_date before start_date. |
DATE_RANGE_TOO_LARGE | 400 | No | Date range exceeds 90-day maximum. |
INVALID_STATUS_FILTER | 400 | No | Invalid status filter value. |
REF_ID_REQUIRED | 400 | No | ref_id query parameter is required (order-status). |
Order Errors
Order Errors
| Parameter | Type | Required | Description |
|---|---|---|---|
PRICE_NOT_MATCH | 409 | No | Price does not match current system price. |
DUPLICATE_REF_ID | 409 | No | An order with this ref_id already exists. |
INSUFFICIENT_BALANCE | 402 | No | Not enough balance to place order. |
PRODUCT_NOT_FOUND | 404 | No | Invalid 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_GATE | 503 | No | No supplier could accept the order. Your balance is not deducted. Safe to retry with the SAME ref_id. |
INTERNAL_ERROR | 500 | No | Unexpected server error. Contact support. |
Availability
Availability Errors
| Parameter | Type | Required | Description |
|---|---|---|---|
MAINTENANCE | 503 | No | The 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.