CSBoard API Error Reference — Every Code and What To Do About It

Every error returns the same JSON shape:

{ "code": "item_unavailable", "detail": "One or more items are no longer available." }

Note the field is detail, not message. Match on code — it is stable and safe to branch on. detail is human-readable and may be reworded without notice.

Some errors carry extra fields alongside code and detail. price_moved includes the current total, item_unavailable may include unavailable_ids and unknown_ids, a per-key rate_limit_exceeded includes bucket, limit_per_min and retry_after_sec, too_many_streams includes max_connections and retry_after_sec, unsupported_game includes supported_app_ids, price_drift includes current_total_usd and min_total_usd, and price_below_market includes market_usd and floor_usd. Ignore unknown fields rather than rejecting the body.

Authentication

HTTP	`code`	Cause	What to do
401	`missing_api_key`	No key sent, or it does not start with `csb_pub_`.	Send `Authorization: Bearer csb_pub_...`.
401	`invalid_api_key`	Key unrecognised or revoked.	Generate a new key at `/profile?tab=api`. Do not retry.
401	`api_key_in_query_string`	The key was sent in the URL (`?api_key=`). Keys are accepted only in a header, because URLs leak into logs, history and `Referer`.	Send `Authorization: Bearer csb_pub_...`. If the key was ever in a URL, rotate it at `/profile?tab=api`.
429	`too_many_failed_auth`	30 bad or missing keys from one IP within a minute — 5-minute IP ban.	Stop, fix the key, wait out the cooldown. Retrying extends nothing but your own outage.
403	`ip_not_allowed`	The key is restricted to an IP allowlist and your address is not on it.	The response quotes the address we saw — add it (or its range) at `/profile?tab=api`, or clear the list.
403	`trading_not_enabled`	Valid key, but trading was never enabled on it.	Toggle trading on that key at `/profile?tab=api`.
403	`account_restricted`	The account is restricted.	Contact support — retrying will not clear it.
403	`steam_account_required`	No Steam account linked, and the order delivers to you.	Link Steam, or use `POST /v1/market/buy` with an explicit trade URL.

Rate limits

HTTP	`code`	Cause	What to do
429	`rate_limit_exceeded`	A per-key limit is spent. `bucket` in the body names it: `read`, `trading` or `buy_orders`. The P2P write limit answers this code too.	Sleep for `Retry-After` seconds — the rest of the current minute — then retry. Pace from the `X-RateLimit-*` headers to avoid it. See Rate Limits.
429	`snapshot_rate_limited`	Bulk snapshot polled more than once a minute.	Cache the snapshot; use ETags to avoid re-downloading it.
429	`too_many_streams`	More than 3 concurrent SSE streams on one key.	Close an idle stream. One stream carries the whole catalogue. A connection that dropped without closing frees its slot within 90 seconds (`Retry-After: 90`).
429	—	More than 1 request a minute to the keyless `GET /v1/public/prices` from one IP. This body is `{ "error": "...", "statusCode": 429 }`, with no `code`.	Sleep for `Retry-After` seconds. The feed only changes once a minute anyway.

Reading market data

HTTP	`code`	Cause	What to do
400	`invalid_param`	A query parameter is malformed — a bad `available_after` timestamp, or a `delivery` value outside `instant` / `up_to_12h` / `hold`, or a `min_refund_percent` outside 0-100. Also a CS2-only filter (`wear`, `min_float`, `max_float`, `stat_trak`, `souvenir`, `available_after`, `sort=newest`) sent with a Dota 2 or Rust `appId`, and an unavailable `appId` on `GET /v1/public/prices`.	Fix the parameter. This is deliberately an error rather than a silently ignored filter.
400	`unsupported_game`	The `appId` is unknown, switched off, or not open to your key. On `POST /v1/orders` it also means your key cannot buy in that game.	Use one of `supported_app_ids` from the body, or check `GET /v1/games`. Do not retry unchanged.
402	`insufficient_settled_balance`	The price feed requires a funded account.	Top up. `GET /v1/health` and `GET /v1/balance` stay open so you can integrate before funding.
202	`snapshot_building`	`GET /v1/listings/snapshot.ndjson.gz`: the file is being built (first request in a while). Not an error, nothing was counted.	Retry in about two minutes.

Buying

HTTP	`code`	Cause	What to do
400	`invalid_request`	Malformed body or parameters.	Fix the request; do not retry unchanged.
400	`unsupported_item`	The item cannot be bought through the API.	Skip it.
400	`invalid_trade_url`	The trade URL on `POST /v1/market/buy` is malformed or private.	Have the end user re-copy their trade URL.
400	`cannot_mix_sources`	One order mixed external-market and platform items.	Split into separate orders.
400	`one_external_per_order`	More than one external-market item in a single order.	One per order.
400	`too_many_items`	More Dota 2 or Rust items than one order takes. `max_items` is in the body (10).	Split into several orders.
402	`insufficient_balance`	Balance does not cover the order.	Top up on the site — there is no card or crypto rail through the API.
403	`external_buy_disabled`	Deliver-to-any-trade-URL buying is not enabled for you.	Ask us to enable it for your account.
403	`kyc_required`	The purchase tripped a KYC threshold.	The account owner completes verification on the site.
409	`price_moved`	Live price rose past your `max_price_usd`. Nothing was charged.	Re-read `price_usd` from `/v1/listings`, decide, retry. The response carries the current total.
409	`item_unavailable`	The listing left the catalogue before your order landed. On CS2 buys, `unknown_ids` names the ids we have no record of: not a listing id (a Steam asset id is the usual mix-up), or a listing gone for over an hour.	Pick another listing, by the `id` from `/v1/listings` or the stream. Subscribe to the SSE stream — `gone` events remove sold items before you try to buy them.
409	`pending_trades_limit`	The recipient has too many unaccepted Steam offers.	Have them accept pending offers first. `limit` is in the body.
409	`held_balance_blocked`	Part of your balance is still inside its reversal hold and cannot fund this order yet. Nothing was charged.	Wait for the hold to clear (`held_usd` in `GET /v1/balance`), or keep the order within `settled_balance_usd`.
409	`concurrent_update`	Another order touched the same items at the same moment, and this one was rolled back. Nothing was charged.	Retry.
409	`idempotency_in_progress`	A request with the same `Idempotency-Key` / `custom_id` is still running.	Wait and poll `GET /v1/orders/info`; do not re-send with a new key or you will double-buy.
409	`price_updating`	Prices are mid-refresh.	Retry in a moment.
409	`not_claimable`	The order is not in a claimable state.	Read `status` — it is already delivering, completed, or failed.
404	`order_not_found`	No such order on this account (`GET /v1/orders/{id}`, `POST /v1/orders/{id}/claim`).	Check the id. Orders are visible only to the account that placed them.
425	`hold_not_cleared`	`POST /v1/orders/{id}/claim`: the item is still inside its hold window.	Retry after `hold_until`, which is in the body.
502	`delivery_failed`	`POST /v1/orders/{id}/claim`: the marketplace rejected the withdrawal. `refunded` in the body says whether the money is already back.	If `refunded` is true, nothing to do. Otherwise we retry or refund on our side; follow the order.
503	`market_unavailable`	The upstream source for that item is temporarily down. No charge was made.	Retry shortly, or pick a listing from elsewhere in the catalogue.
504	`upstream_timeout`	The marketplace did not answer in time, so the outcome is unknown: the purchase may still have gone through.	Poll `GET /v1/orders/info` with the saved identifier. Keep an empty result pending and investigate before submitting another purchase.
500	`order_failed`	Unexpected failure.	Check `GET /v1/orders/info` with your `custom_id` before retrying — the order may exist.

An order that was accepted and fails later is not an HTTP error. It ends failed or cancelled, the money comes back in refund, and fail_reason, fail_side and fail_message say why. Every code and what to do about it is listed under why an order failed.

P2P listing

HTTP	`code`	Cause	What to do
400	`idempotency_key_required`	`POST /v1/p2p/listings` without an `Idempotency-Key` header of 8–128 characters.	Send one, unique per publish request.
400	`no_capable_client`	Nothing on your side can send the Steam trade.	Run the CSBoard extension or app, then retry.
403	`contact_required`	No verified email and no linked Telegram to tell you about a sale.	Add one on the site.
403	`account_banned`	This account is banned.	Contact support. Retrying will not clear it.
403	`shop_locked` / `p2p_cooldown` / `p2p_suspended` / `trading_banned`	Selling on P2P is locked for this account.	Wait until the time in the body, where there is one. Retrying sooner changes nothing.
409	`asset_revision_changed`	The item changed after you read the inventory.	Read `GET /v1/p2p/inventory` again and resend with the new `asset_revision`.
409	`snapshot_stale`	Our read of your inventory is out of date. The body carries `inventory_proof`.	Poll the inventory after `retry_after_ms`, then resend.
409	`listing_not_active`	The listing has sold, is mid-sale or was removed.	Nothing to remove. Read `GET /v1/p2p/listings`.
409	`idempotency_key_mismatch` / `idempotency_key_consumed`	The key was used with different details, or an earlier attempt with it failed.	Resend with a new `Idempotency-Key`.
422	`price_below_market`	The price is under half of our market price for the item. Over a key it cannot be confirmed past.	Raise `price_usd` to at least `floor_usd` from the body. The `Idempotency-Key` is not spent.
503	`p2p_disabled`	The P2P market is switched off.	Retry later.
503	`p2p_reprice_disabled`	Price changes on the P2P market are switched off.	Retry later.
500	`internal_error`	Something went wrong on our side. Also answered by Instant Sell.	Retry later. Before retrying a write, read the current state (`GET /v1/p2p/listings`, `GET /v1/sell/orders`).

Instant sell

HTTP	`code`	Cause	What to do
403	`selling_not_enabled`	Instant Sell is invite-only and not enabled for this key.	Ask support to enable it. `GET /v1/sell/status` shows the state.
409	`price_drift`	The total the sell order would book is below your `min_total_usd`. It is checked after the items are grouped into offers. Nothing happened.	Re-quote, decide, retry. The body carries `current_total_usd` and `min_total_usd`.
409	`item_not_in_inventory`	An asset id has no live quote any more.	Re-quote and retry.
409	`active_order_exists`	This seller already has an open trade offer from us.	Wait for it to finish, or cancel the order.
409	`not_cancellable`	The sell order is past `offer_sent`, or one of its offers was accepted.	Nothing to do; follow it to settlement.
422	`unsupported_game`	The `app_id` is not open for instant sell on this key.	Use one of `supported_app_ids` from the body. Do not retry unchanged.
503	`sell_disabled`	Instant Sell is switched off right now. Reads keep working.	Retry later. Orders in flight continue and settle as normal.

The full list is in the Instant Sell guide.

Webhooks

HTTP	`code`	Cause	What to do
400	`invalid_webhook_url`	Not absolute HTTPS, embeds credentials, or resolves to a private address.	Register a publicly routable HTTPS URL.
404	`not_found`	No such webhook or delivery on your account.	Check the id with `GET /v1/webhooks`.
409	`too_many_webhooks`	5 endpoints already registered.	Delete one first.
409	`already_delivered`	You retried a delivery that already succeeded.	Nothing to do.

MCP server

HTTP	`code`	Cause	What to do
405	`method_not_allowed`	`GET` on `/mcp`. The server is stateless and speaks only `POST`.	Send JSON-RPC with `POST /mcp`. See automation.

Not available through the API

HTTP	`code`	Meaning
501	`not_implemented`	Withdrawals are site-only by design. Manage payouts at csboard.com/profile.

Retry rules

The distinction that matters is whether money moved.

Safe to retry

429 (after Retry-After), price_updating, market_unavailable, concurrent_update, held_balance_blocked (once the hold clears). Respect the returned error code and keep the same order identifier.

Do not retry unchanged

400, 401, 403, invalid_webhook_url, unsupported_item. The request is wrong; repeating it produces the same error and, on auth failures, an IP ban.

Decide, then retry

price_moved and item_unavailable. The market changed under you. Re-read the listing, apply your own pricing rule, and issue a new order with a new idempotency key.

Check before retrying

order_failed, upstream_timeout, idempotency_in_progress, and any timeout on POST. Call GET /v1/orders/info with your custom_id first — the order may already exist.

A lost purchase response leaves the outcome unknown. Successful responses are cached for up to 24 hours. Once the cache expires, the same identifier can start another purchase. Keep the original order pending until you reconcile it.

Get Started

Walkthroughs

CSBoard API Error Reference — Every Code and What To Do About It

Authentication

Rate limits

Reading market data

Buying

P2P listing

Instant sell

Webhooks

MCP server

Not available through the API

Retry rules

Safe to retry

Do not retry unchanged

Decide, then retry

Check before retrying

​Authentication

​Rate limits

​Reading market data

​Buying

​P2P listing

​Instant sell

​Webhooks

​MCP server

​Not available through the API

​Retry rules

Safe to retry

Do not retry unchanged

Decide, then retry

Check before retrying

Authentication

Rate limits

Reading market data

Buying

P2P listing

Instant sell

Webhooks

MCP server

Not available through the API

Retry rules