Errors

Merchant API errors use the platform error body:

json

{
  "statusCode": 422,
  "message": "Product SKU PAPER-404 was not found",
  "error": "Unprocessable Entity",
  "code": "PRODUCT_SKU_NOT_FOUND",
  "details": { "sku": "PAPER-404" },
  "requestId": "…",
  "timestamp": "2026-09-06T05:00:00.000Z",
  "path": "/api/v1/merchant/orders"
}

Status	When
`400`	Malformed request or missing `Idempotency-Key`
`401`	Missing, invalid, revoked, or expired API key; inactive merchant
`403`	Key is valid but missing the required scope
`404`	Order not found for this merchant
`409`	Idempotency or `externalOrderId` conflict
`422`	Valid JSON that fails business rules (SKU, phone, currency, collection)
`429`	Per-key rate limit; see `Retry-After`
`503`	Required dependency unavailable (`DEPENDENCY_UNAVAILABLE`)

code is stable for programmatic handling. Messages may be refined.

Code	Meaning
`MERCHANT_API_AUTH_REQUIRED`	Missing `Authorization: Bearer chu_live_...`
`MERCHANT_API_KEY_INVALID`	Secret is malformed or unknown
`MERCHANT_API_KEY_REVOKED`	Key was revoked
`MERCHANT_API_KEY_EXPIRED`	`expiresAt` is in the past
`MERCHANT_API_SCOPE_DENIED`	Missing `orders:write` / `orders:read` / `orders:cancel` / `products:read` / `products:write`
`MERCHANT_INACTIVE`	Merchant is not `ACTIVE`
`MERCHANT_API_RATE_LIMITED`	Per-key limit exceeded
`DEPENDENCY_UNAVAILABLE`	A required dependency failed closed
`MERCHANT_API_IDEMPOTENCY_CONFLICT`	Same key, different body
`MERCHANT_API_IDEMPOTENCY_IN_PROGRESS`	Fresh in-flight request with the same key
`PRODUCT_SKU_NOT_FOUND`	Unknown SKU for this merchant
`PRODUCT_SKU_INACTIVE`	SKU exists but is inactive
`EXTERNAL_ORDER_CONFLICT`	`externalOrderId` already bound to different commercial data
`MERCHANT_API_INVALID_ORDER`	Collection / payload semantics are illegal
`MERCHANT_API_CURRENCY_UNSUPPORTED`	Not `MNT`

Stack traces, database errors, and credential values are never returned.

Errors ​

Errors