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 or IP not whitelisted
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": "invalid IP: 203.0.113.42"
}

Fix: Add your server's IP address to the merchant whitelist.

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.

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

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