Errors

API-generated error responses use this shape:

{
  "error": {
    "code": "MERCHANT_PRICE_CHANGED",
    "message": "Live price exceeds max_price"
  }
}

code is the stable contract — match on it programmatically. message is human prose; do not pattern-match on it. Gateways or transport failures may return no JSON body. Use the code and the recovery rules below together; a timeout or 5xx does not prove that a purchase failed.

Catalogue of codes

Auth (every endpoint)

See the canonical authentication failure table. Both missing and invalid keys return 401 MERCHANT_API_KEY_MISSING.

Catalog (GET /merchant/items*)

Purchase (POST /merchant/buy, POST /merchant/buy-sync, POST /merchant/buy-by-name, GET /merchant/purchases*)

Anything else

If you see > 5 transient errors in a minute, pause traffic for ~30s and retry behind a circuit breaker.

Retry guidance

These are rules for calling the HTTP API. Your webhook receiver has a separate delivery retry policy. After a WebSocket disconnect, follow the close-code recovery table.

Idempotency

POST /merchant/buy, POST /merchant/buy-sync, and POST /merchant/buy-by-name are the purchase endpoints, and they share one idempotency key per merchant: custom_id. Persist a stable value (for example, your internal order ID) before sending the first POST. A replay does not start a second purchase operation; fields such as status and balance may reflect their current values rather than the original response.

The identity check on /buy and /buy-sync matches when the new request has the same (item_id, target_steam_id, target_trade_url) and the existing order’s price still fits under the new max_price. Any mismatch — including a max_price lowered below the existing order’s debited price — returns 409 MERCHANT_DUPLICATE_CUSTOM_ID.

For POST /buy-by-name, identity keys off custom_id alone. A re-submit after the previous call’s retry cycle has finished returns its existing final attempt. A re-submit while that cycle is still running can return the current attempt. The original cycle may later create another attempt with a different purchase_id; a failed attempt alone does not prove that the whole cycle has ended. The replay does not start a fresh cycle. Correlate your business order by custom_id and retain the purchase IDs of its attempts. /buy and /buy-sync replays return the existing purchase ID.

Idempotency is tied to the stored purchase. Do not reuse a custom_id for another business order. See purchase idempotency for the response semantics of each method.

Purchase failure codes

failure.code describes an existing purchase. It is separate from HTTP error.code (MERCHANT_*), which describes the request outcome. The same reasons are used by GET purchase, the purchase list, synchronous failure details and new purchase webhooks (data.failure_code). Match the code, not the message.

A malformed trade URL is rejected before purchase creation as MERCHANT_INVALID_TRADE_URL. A syntactically valid URL with a revoked token can fail later as INVALID_TRADE_URL. Generic trading restrictions do not establish which of these happened. Some providers cannot distinguish decline from a counteroffer and return TRADE_CANCELLED or UNKNOWN.

Codes describe reasons, not refund eligibility. Check refunded_amount: a positive value confirms the recorded refund, 0 explicitly means no refund, and null (or an omitted webhook field) means no refund is reported by that response. Ordinary merchant expiry refunds retain their existing fee exemption. A buyer’s rollback after delivery receives no refund, a seller’s rollback receives the full price, and an unknown rollback initiator requires manual review without automatic refund.

trade_offer_id is retained whenever supplied, including on failure. Null means the ID is unknown; it does not prove that no offer was sent. A later response with no ID does not erase an earlier known ID. No ID is synthesized.

Compatibility

Old purchases without a stored normalized reason use recognized shared categories or UNKNOWN; we cannot reconstruct a lost reason from an old generic message. GET/list do not rewrite purchase history. Already-saved webhook payloads and their retries retain their original codes/messages and may omit the newer offer fields. No events are automatically recreated or replayed. Accept historical and future codes as an unknown reason, and reconcile by purchase ID and the reported amounts.