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, 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.
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`	Per-key limit exceeded.	Sleep for `Retry-After` seconds, then retry. 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.
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.

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.
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 sold before your order landed.	Pick another listing. 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	`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.
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.
500	`order_failed`	Unexpected failure.	Check `GET /v1/orders/info` with your `custom_id` before retrying — the order may exist.

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	`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.

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.

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, 503, and network timeouts. Nothing was charged. Reuse the same Idempotency-Key so a request that actually succeeded replays instead of buying twice.

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, idempotency_in_progress, and any timeout on POST. Call GET /v1/orders/info with your custom_id first — the order may already exist.

A timeout is not a failure. POST /v1/orders and POST /v1/market/buy are idempotent on Idempotency-Key / custom_id: retrying with the same value replays the original order. Retrying with a new value after a timeout is how you buy the same skin twice.

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

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

​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

Not available through the API

Retry rules