Core conceptsError code reference
Error code reference
Every error returns a stable machine-readable code in the envelope
{ success:false, error:{ code, message } }. Branch on code, never on message.
The per-endpoint pages list the codes each route can raise; this is the consolidated reference.
Authentication & signing
| Code | When it happens · fix |
|---|---|
| INVALID_CREDENTIALS | Client ID/secret unknown, or a credential used against the wrong host (sandbox mp_… vs production mp_live_…). Pair each credential with its own host. |
| INVALID_SIGNATURE | The signature does not match the base string. Re-check the base string against the Authentication worked example. |
| MISSING_NONCE · INVALID_NONCE | Nonce header absent or malformed. Send a fresh 32–64 lowercase-hex nonce, unique per request. |
| NONCE_REUSED | That nonce was already used. Generate a new one per request. |
| TIMESTAMP_EXPIRED | Timestamp outside the allowed window. Sync your clock; send Unix seconds, not milliseconds. |
| HMAC_VERSION_DEPRECATED | Old signature version. Send X-MallPlus-Signature-Version: 3. |
| SELLER_TOKEN_REQUIRED | A seller-scoped call without seller headers. Add X-MallPlus-Access-Token and X-MallPlus-Seller-Id. |
| UNAUTHORIZED | The seller access token is invalid or expired (401 on a seller-scoped call). Refresh the token; on repeat, re-run the consent flow. |
Seller authorization
| Code | When it happens · fix |
|---|---|
| REDIRECT_URL_MISMATCH | The redirect_uri does not match the app config exactly. Use the registered URI. |
| INVALID_AUTHORIZATION_CODE | The authorization code is unknown or invalid. |
| AUTH_CODE_EXPIRED · AUTH_CODE_USED | Codes expire in 10 minutes and are single-use. Exchange immediately; never twice. |
| INVALID_REFRESH_TOKEN · REFRESH_TOKEN_EXPIRED | Refresh token invalid or expired. Re-run the consent flow. |
| REFRESH_TOKEN_REUSED | A rotated-out refresh token was replayed; the chain is revoked. Single-flight your refreshes, then re-authorize. |
| AUTHORIZATION_REVOKED · RE_AUTHORIZATION_REQUIRED | The seller revoked access or consent changed. Ask the seller to re-authorize. |
| TOKEN_REVOKED | The token chain was revoked — typically after refresh-token reuse was detected. Stop calling for this seller and re-run the consent flow. |
Requests & idempotency
| Code | When it happens · fix |
|---|---|
| VALIDATION_ERROR · BAD_REQUEST | Body or parameters failed validation. Check the field rules on the endpoint page. |
| INVALID_JSON | The body is not valid JSON. |
| PAYLOAD_TOO_LARGE | Body exceeds the 1 MB cap. |
| NOT_FOUND · CATEGORY_NOT_FOUND | Resource missing, or not visible to this seller. |
| CONCURRENT_MODIFICATION | The resource changed under you. Re-read and retry. |
| IDEMPOTENCY_KEY_REQUIRED | A high-risk write needs an Idempotency-Key. Add one. |
| IDEMPOTENCY_KEY_IN_PROGRESS | The same key is still executing. Retry after Retry-After. |
| IDEMPOTENCY_KEY_REUSED | Same key, different body. Use a fresh key per distinct request. |
| CONFLICT | The request conflicts with existing state — e.g. re-running consent with different scopes than the active grant. Resolve the existing state first (revoke, then re-authorize). |
| WEBHOOK_SUBSCRIPTION_EXISTS | The app already has a subscription for that event type (409). Update or delete the existing subscription instead of creating a duplicate. |
Orders, shipment & returns
| Code | When it happens · fix |
|---|---|
| ORDER_NOT_CANCELLABLE | The order is past the cancellable window (only READY_TO_SHIP can cancel). Handle it as a return. |
| INVALID_TRANSITION | An illegal status change was attempted. |
| SHIPMENT_ALREADY_ARRANGED | A shipment is already booked for this order. |
| SHIPMENT_NOT_ARRANGED | Tracking or label requested before the shipment was arranged. |
| INVALID_PICKUP_DATE · PICKUP_DATES_UNAVAILABLE | Pickup date rejected by platform rules, or no eligible dates (e.g. already shipped). |
| SHIPPING_LABEL_UNAVAILABLE | Label requested before the shipment was arranged. |
| INVALID_RETURN_REASON | The dispute reason is not in the allowed list (see GET /returns/dispute-reasons). |
| RETURN_PAST_DEADLINE | The return or dispute window has closed. |
Rate limits & system
| Code | When it happens · fix |
|---|---|
| RATE_LIMITED | Per-app or per-developer rate limit exceeded. Back off per Retry-After. |
| SANDBOX_ONLY | A sandbox-only route was called with a live credential. |
| UPSTREAM_ERROR | A platform dependency failed. Retry with backoff. |