Guides

Errors & limits

Every error has the same shape. Branch on code — messages are for people and may change.

HTTP 422

{
  "error": {
    "code": "price_below_minimum",
    "message": "Item 1 is priced Rs 900; the minimum resale price is Rs 1200",
    "details": [{ "index": 0, "resalePrice": 900, "minResalePrice": 1200 }]
  }
}

Error codes#

400 Bad request

code	Meaning	What to do
`validation_error`	A field is missing or invalid; details lists each problem.	Fix the request — retrying will not help.
`idempotency_key_required`	POST /orders without an Idempotency-Key header.	Send your order id as the key.

401 Unauthorized

code	Meaning	What to do
`invalid_key`	Missing, unknown or revoked key, or wrong secret.	Check the key; create a new one if lost.

403 Forbidden

code	Meaning	What to do
`ip_not_allowed`	The key is restricted to other IP addresses.	Call from an allowed server or create a key without a restriction.
`reseller_suspended`	Your account is suspended; the message says why.	Contact support.
`reseller_not_active`	Live keys work once your application is approved.	Use a test key until then.
`dropship_disabled`	Dropshipping is paused platform-wide for a while.	Retry later; test keys keep working.

404 Not found

code	Meaning	What to do
`not_found`	No such order, import or product for this key.	Check the id and that you use the right mode (live/test).
`variant_not_found`	Unknown variant, or no longer dropshippable.	Refresh the product; hide it if it is gone.
`variant_not_mapped`	externalVariantId was never mapped.	Map it with POST /imports, or send variantId.

409 Conflict

code	Meaning	What to do
`duplicate_order`	This externalOrderId was already received (details.id).	Look it up with GET /orders?externalOrderId=…
`idempotency_key_reused`	The key was used with a different body.	Use a new key for a new order.
`idempotency_in_progress`	The first request with this key is still running.	Retry in a few seconds.
`order_not_cancellable`	Already packed or further.	Ask your customer to refuse it, or arrange a return.
`order_not_payable`	The order is not awaiting funds.	No action needed.

422 Unprocessable

code	Meaning	What to do
`price_below_minimum`	resalePrice is under minResalePrice.	Raise your price.
`cod_below_cost`	The COD amount does not cover wholesale + shipping.	Raise the price or the delivery charge.
`out_of_stock`	Not enough stock (details has what is available).	Lower the quantity or hide the product.
`insufficient_balance`	Your wallet cannot cover the return reserve or prepaid cost.	Top up your wallet.
`deposit_required`	Your security deposit is not complete.	Top up your wallet.
`prepaid_disabled`	Prepaid orders are not offered right now.	Send the order as COD.
`customer_blocked`	The customer refused too many parcels.	Ask for prepayment, or decline the order.
`test_mode_only`	/simulate was called with a live key.	Use a test key.
`webhook_url_invalid`	The webhook URL is not public HTTPS.	Use a public https:// address.

429 Too many requests

code	Meaning	What to do
`rate_limited`	Over your API plan's requests a minute (all your keys together).	Wait for Retry-After seconds.
`daily_quota_exceeded`	Your API plan's requests for the day are used up. Orders still go through.	Wait until midnight UTC (X-Quota-Reset), or buy a bigger plan in Dropshipping → API plan.
`daily_cap_reached`	Your tier's daily order limit.	Try tomorrow; the limit grows with delivered orders.

5xx Server error

Something failed on our side (internal_error). Retry with backoff; for POST /orders keep the same Idempotency-Key so a retry cannot create a second order.

Limits are per account — all your keys together — and come from your API plan. The free plan allows 5,000 requests a day and 120 a minute, plenty for a normal store: the WooCommerce plugin and the Shopify app use a few hundred a day. Bigger plans are bought from your wallet in Dropshipping → API plan.

Over the per-minute rate: 429 rate_limited with a Retry-After header (seconds).
Over the day's requests (UTC): 429 daily_quota_exceeded until midnight UTC. Every response carries X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset (Unix seconds).
Never refused for the daily quota: POST /orders, cancelling and paying for an order, POST /shipping/quote and GET /me.

Do not call the API on every page view. Import products into your own store, keep them current from webhooks, and check stock with GET /inventory at checkout. Catalog responses are cached for about a minute on our side, so calling more often only spends your quota.

Idempotency#

POST /orders requires an Idempotency-Key header (up to 255 characters). Your own order id is a good key.
The same key with the same body returns the first response again, with Idempotent-Replayed: true. With a different body it is 409 idempotency_key_reused.
Keys are remembered for 7 days.
Independently, an externalOrderId can only be used once per account (409 duplicate_order).

Pagination#

Lists take limit (1–100, default 50) and return { data, nextCursor }. Pass nextCursor as cursor for the next page; it is null on the last one.

Conventions#

Amounts are integers in Pakistani rupees.
Times are ISO 8601 in UTC.
Ids are opaque strings — store them as text.
Versioning: new fields and events can appear at any time — ignore what you do not know. Anything breaking ships as /v2 alongside /v1.

API reference →

Which errors each endpoint returns.

Orders & money →

Where most 422s come from.