Error Handling

All API errors follow a consistent format and use standard HTTP status codes.

Error Response Format

{
  "success": false,
  "message": "Description of what went wrong"
}

TIP

The data field is only present when there are additional details (e.g., validation errors). It is omitted entirely — not null — for simple errors.

Validation errors include field-level details in data:

{
  "success": false,
  "message": "validation error",
  "data": [
    {
      "field": "InventoryRequest.game",
      "code": "required",
      "message": "game is a required field"
    },
    {
      "field": "InventoryRequest.partner",
      "code": "required",
      "message": "partner is a required field"
    }
  ]
}

HTTP Status Codes

Code	Meaning	When
200	Success	Request completed successfully
400	Bad Request	Invalid JSON body, validation errors
401	Unauthorized	Missing or invalid API key
403	Forbidden	Merchant account disabled, IP not whitelisted, or the endpoint is not enabled for your account
404	Not Found	Resource doesn't exist (e.g., unknown tx_id or merchant_tx_id)
408	Request Timeout	Upstream request timed out
409	Conflict	Resource already exists (e.g., duplicate merchant_tx_id)
500	Internal Server Error	Something went wrong on our side
502	Bad Gateway	Upstream service error

Common Errors

Missing API Key

Status: 401

{
  "success": false,
  "message": "missing authorization header"
}

Fix: Include X-Api-Key header in your request.

Invalid API Key

Status: 401

{
  "success": false,
  "message": "invalid API key"
}

Fix: Check that your API key is correct and active.

Merchant Disabled

Status: 403

{
  "success": false,
  "message": "merchant account is disabled"
}

Fix: Contact support to reactivate your merchant account.

IP Not Whitelisted

Status: 403

{
  "success": false,
  "message": "IP not whitelisted: 203.0.113.42"
}

Fix: Add your server's IP address to the merchant whitelist. Entries are exact IPs — ranges (CIDR) are not supported. An empty whitelist allows any IP.

Invalid Request Body

Status: 400

{
  "success": false,
  "message": "invalid request body"
}

Fix: Ensure the request body is valid JSON.

Validation Error

Status: 400

{
  "success": false,
  "message": "validation error",
  "data": [
    {
      "field": "InventoryRequest.token",
      "code": "len",
      "message": "token must be exactly 8 characters long"
    }
  ]
}

Fix: Check each field error and correct the input.

Not Found

Status: 404

{
  "success": false,
  "message": "not found error"
}

Fix: Verify the id, merchant_tx_id, or tx_id is correct.

Timeout

Status: 408

{
  "success": false,
  "message": "timeout error"
}

Fix: Upstream service was slow. Retry after a few seconds.

Already Exists

Status: 409

{
  "success": false,
  "message": "already exist error"
}

Fix: The merchant_tx_id has already been used. Use a unique transaction ID.

Too Many Items

Status: 400

{
  "success": false,
  "message": "deposit exceeds the maximum of 50 items per deposit"
}

Fix: The deposit has more items than the per-deposit limit, so it is rejected before trade creation. The limit is configurable — read the current value from max_items in the Get Inventory response and split the deposit into smaller batches.

Domain-Specific Validation Errors

Beyond standard field validation, some errors indicate issues with the user's Steam account or trade eligibility. These are returned as validation errors (400) with specific code values in the data array.

Deposit & Intent Errors

These errors may occur when calling Create Intent or Create Deposit:

Field	Code	Message	Description
merchant_tx_id	exist	The specified value already exists	The merchant_tx_id has already been used. Use a unique ID for each deposit.
—	price_changed	price_changed	from_preview deposits only: the cart cannot be accepted as it stands. The response data carries the current pricing of the same items and names the blocking ones in data.rejected — re-show and retry. No deposit was created; the merchant_tx_id can be reused.
—	preview_unavailable	preview_unavailable	from_preview deposits only: preview pricing is temporarily unavailable. Retry later or use the regular Get Inventory flow. No deposit was created.
inventory	inventory_reload	Please reload the inventory	Inventory data is stale. Fetch a fresh inventory before creating a deposit.
token	trade_link_revoked	The trade link has been revoked by the account owner	The user has reset their Steam trade URL. Ask them to provide a new one.
partner	trade_link_invalid	The trade link is invalid or has expired	The Steam trade link is incorrect or no longer valid.
partner	trade_banned	The account is trade banned on Steam	The user's Steam account has a trade ban. Trading is not possible.
partner	profile_private	The user's profile is private, trade is not possible	The user must set their Steam profile to public for trading.
partner	limited_account	Limited Steam account — trading is not available	The user has a limited Steam account (hasn't spent $5 on Steam). Trading is unavailable.
partner	hold	A temporary trade restriction is active	The user's account has a temporary Steam trade hold. They must wait for it to expire.
game	permissions	Insufficient permissions to access the specified game	The user's Steam inventory for this game is private or inaccessible.
partner	hold_and_permissions	A trade restriction is active and there are insufficient permissions for the specified game	Combination of trade hold and game permission issues.

Purchase Errors

These errors may occur when calling Create Purchase. The user's trade link is checked before the purchase is created: on any of these errors no purchase is created and nothing is charged — fix the trade link and retry, the same merchant_tx_id can be reused.

Field	Code	Message	Description
token	trade_link_revoked	The trade link has been revoked by the account owner	The user has reset their Steam trade URL. Ask them to provide a new one.
partner	trade_link_invalid	The trade link is invalid or has expired	The Steam trade link is incorrect or no longer valid.
partner	trade_banned	The account is trade banned on Steam	The user's Steam account has a trade ban.
partner	profile_private	The user's profile is private, trade is not possible	The user must set their Steam profile to public.
partner	limited_account	Limited Steam account — trading is not available	The user has a limited Steam account.
game	permissions	Insufficient permissions to access the specified game	The user's account cannot receive items in this game.

INFO

A temporary Steam trade hold on the user's account does not block purchases — the account can still receive items. hold and hold_and_permissions apply to deposits only.

Inventory Errors

These errors may occur when calling Get Inventory:

Field	Code	Message	Description
inventory	inventory_reload	Please reload the inventory	Inventory data is stale. Retry the request.
token	trade_link_revoked	The trade link has been revoked by the account owner	The user has reset their Steam trade URL. Ask them to provide a new one.
partner	trade_link_invalid	The trade link is invalid or has expired	The Steam trade link is incorrect or no longer valid.
partner	trade_banned	The account is trade banned on Steam	The user's Steam account has a trade ban.
partner	profile_private	The user's profile is private, trade is not possible	The user must set their Steam profile to public.
partner	limited_account	Limited Steam account — trading is not available	The user has a limited Steam account.
partner	hold	A temporary trade restriction is active	The user's account has a temporary Steam trade hold.
game	permissions	Insufficient permissions to access the specified game	The user's Steam inventory for this game is private.
partner	hold_and_permissions	A trade restriction is active and there are insufficient permissions for the specified game	Combination of trade hold and game permission issues.

Example: Steam Account Error

Status: 400

{
  "success": false,
  "message": "validation error",
  "data": [
    {
      "field": "partner",
      "code": "trade_banned",
      "message": "The account is trade banned on Steam"
    }
  ]
}

Fix: Inform the user about their Steam account issue. These errors require action from the user, not from your integration.

TIP

For the best user experience, map error code values to user-friendly messages in your UI. The code field is stable and can be used for programmatic error handling, while message provides a human-readable description.

Best Practices

1. Always check success — Don't assume a 200 response means success
2. Handle 502 gracefully — Upstream outages are temporary
3. Parse validation errors — The data array tells you exactly which fields failed
4. Log error responses — Include the full response body for debugging
5. Implement retries — For 408/500/502 errors, retry with exponential backoff