> ## Documentation Index
> Fetch the complete documentation index at: https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Coinbase Advanced Trade API Error Codes and Responses

> Reference for all Coinbase Advanced Trade API error codes, HTTP status codes, and how to handle errors in your integration.

All errors returned by the Coinbase Advanced Trade API follow a consistent structure: every failed request produces both an HTTP status code and a JSON response body that contains machine-readable error identifiers alongside human-readable descriptions. By inspecting both the `error` field and the HTTP status code, you can build robust error-handling logic that distinguishes between transient server issues worth retrying and permanent client-side mistakes that require a code fix.

## Error Response Format

When a request fails, the API returns a JSON body with the following shape:

```json theme={null}
{
  "error": "INVALID_ARGUMENT",
  "message": "The requested product is not found",
  "error_details": "product_id BTC-XYZ is not a valid product",
  "preview_failure_reason": "",
  "new_order_failure_reason": ""
}
```

| Field | Type | Description |
| - | - | - |
| `error` | string | Machine-readable error code. Use this field in conditional logic — not the `message`. |
| `message` | string | Human-readable summary of what went wrong. |
| `error_details` | string | Additional context about the specific failure, such as the invalid value that was supplied. |
| `preview_failure_reason` | string | Populated when an order preview fails, indicating why the order would be rejected. |
| `new_order_failure_reason` | string | Populated when a live order submission fails at the exchange level. |

## HTTP Status Codes

The HTTP status code gives you a broad category of the failure. Always combine it with the `error` field for precise handling.

| Status | Meaning |
| - | - |
| `400` | **Bad Request** — One or more request parameters are invalid or missing. |
| `401` | **Unauthorized** — Your JWT is missing, malformed, or expired. |
| `403` | **Forbidden** — Your API key does not have the required permissions for this operation. |
| `404` | **Not Found** — The requested resource (order, product, portfolio) does not exist. |
| `429` | **Too Many Requests** — You have exceeded the rate limit for this endpoint. |
| `500` | **Internal Server Error** — An unexpected error occurred on the Coinbase side. |

> [!WARNING]
>
> When you receive a `429 Too Many Requests` response, you **must** stop sending requests immediately and apply exponential backoff before retrying. Continuing to send requests while rate-limited can result in longer cooldown periods or temporary key suspension.

## Common Error Codes

The `error` field in the response body contains one of the following string identifiers. Use these values — not HTTP status codes — as the primary key for branching your error-handling logic.

> [accordion] UNKNOWN\_FAILURE\_REASON
>
> An unexpected or unclassified error occurred. This code is returned when the failure does not map to any known error category. If you encounter this consistently, capture the full response body and contact Coinbase support with your request details and timestamp.

> [accordion] INVALID\_ARGUMENT
>
> One or more of the parameters you supplied in the request body or query string are invalid. Check the `error_details` field for the specific parameter name and the value that was rejected. Common triggers include malformed `product_id` strings, out-of-range numeric values, or missing required fields.

> [accordion] NOT\_FOUND
>
> The resource you are trying to access does not exist. This can occur when referencing an `order_id` that has already been cancelled and purged, a `product_id` that is not listed on the exchange, or a `portfolio_uuid` that belongs to a different account. Double-check identifiers and ensure you are querying the correct environment.

> [accordion] INSUFFICIENT\_FUND
>
> Your account does not have enough available balance to place the order as specified. This may be because funds are currently held against other open orders. Review your `available_balance` via the [Get Account](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/accounts/get-account.md) endpoint before submitting the order, and cancel any unnecessary open orders to free up held funds.

> [accordion] ORDER\_ENTRY\_DISABLED
>
> Order entry has been temporarily halted for the specified trading pair. This typically happens during scheduled maintenance windows or in response to unusual market conditions. Check the [Coinbase status page](https://status.coinbase.com) for active incidents and retry once trading is re-enabled.

> [accordion] INVALID\_PRODUCT\_ID
>
> The `product_id` you provided does not match any active trading pair on the exchange. Product IDs are case-sensitive and follow the `BASE-QUOTE` format (for example, `BTC-USD` or `ETH-USDC`). Use the [List Products](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/products/list-products.md) endpoint to retrieve the full list of valid, tradeable product IDs.

> [accordion] INVALID\_SIDE
>
> The `side` field in your order request must be either `"BUY"` or `"SELL"` (uppercase). Any other value — including lowercase variants — will produce this error. Check your serialization layer to ensure enum values are not being lowercased before the request is sent.

> [accordion] INVALID\_ORDER\_TYPE
>
> The order configuration object you provided does not match any supported order type. Supported configurations include `market_market_ioc`, `limit_limit_gtc`, `limit_limit_gtd`, `stop_limit_stop_limit_gtc`, and `stop_limit_stop_limit_gtd`. Ensure your request body contains exactly one order-type configuration object with the correct field names.

> [accordion] DUPLICATE\_CLIENT\_ORDER\_ID
>
> The `client_order_id` you specified has already been used for a previous order on this account. Client order IDs must be globally unique per account. Generate a new UUID for each order submission, or implement a deterministic naming scheme (for example, combining a strategy ID with a monotonically increasing counter) to prevent collisions.

> [accordion] RATE\_LIMIT\_EXCEEDED
>
> Your API key has sent too many requests within the allowed time window. Implement exponential backoff with jitter and reduce your request frequency. Consider switching to the [WebSocket Advanced Trade feed](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/guides/websocket-feed.md) for real-time market data instead of polling REST endpoints.

> [accordion] INVALID\_LIMIT\_PRICE
>
> The `limit_price` you specified for a limit or stop-limit order is outside the acceptable range for the product. Prices must be positive, must respect the product's `quote_increment` precision, and cannot be unreasonably far from the current market price (to protect against fat-finger errors). Retrieve the product details to check the `quote_increment` and current price before submitting.

> [accordion] INVALID\_BASE\_SIZE / INVALID\_QUOTE\_SIZE
>
> The quantity you specified does not meet the product's size constraints. For `base_size`, the value must be greater than or equal to the product's `base_min_size` and must be a multiple of `base_increment`. For `quote_size` (used with market buy orders), the value must be at least the product's `min_market_funds`. Retrieve the product details from the [Get Product](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/products/get-product.md) endpoint to check these limits before placing an order.

## Best Practices for Error Handling

Following these patterns will make your integration more resilient to transient failures and easier to debug when things go wrong.

### Retry with Exponential Backoff on 5xx Errors

Server-side errors (`500`, `502`, `503`) are often transient. Rather than failing immediately, retry the request after a progressively longer delay:

```python theme={null}
import time
import random
import requests

def request_with_retry(method, url, **kwargs):
    max_retries = 5
    base_delay = 1.0  # seconds

    for attempt in range(max_retries):
        response = requests.request(method, url, **kwargs)

        if response.status_code < 500:
            # Client errors and successes — do not retry
            return response

        if attempt < max_retries - 1:
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            print(f"Server error {response.status_code}. Retrying in {delay:.2f}s...")
            time.sleep(delay)

    return response  # Return final response after exhausting retries
```

### Check the `error` Field, Not Just the HTTP Status

Two different errors can share the same HTTP status code. Always branch on the `error` string for precise handling:

```python theme={null}
response = requests.post(url, json=order_payload, headers=headers)
body = response.json()

match body.get("error"):
    case "INSUFFICIENT_FUND":
        print("Not enough balance — cancel open orders or deposit funds.")
    case "DUPLICATE_CLIENT_ORDER_ID":
        print("Order already submitted — check existing orders before retrying.")
    case "RATE_LIMIT_EXCEEDED":
        print("Slow down — apply backoff before next request.")
    case _:
        print(f"Unhandled error: {body.get('error')} — {body.get('message')}")
```

### Use `client_order_id` for Idempotency

Network failures can leave you uncertain about whether an order was actually created. By setting a unique `client_order_id` on every order, you can safely re-submit the request — if the order already exists, you will receive a `DUPLICATE_CLIENT_ORDER_ID` error instead of a duplicate order being placed. Use the existing order's details (retrievable via [Get Order](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/orders/get-order.md)) to determine the true state.

```python theme={null}
import uuid

order_payload = {
    "client_order_id": str(uuid.uuid4()),  # Unique per order attempt
    "product_id": "BTC-USD",
    "side": "BUY",
    "order_configuration": {
        "limit_limit_gtc": {
            "base_size": "0.001",
            "limit_price": "30000.00"
        }
    }
}
```

> [!NOTE]
>
> Store the `client_order_id` you generate before sending the request — not after. If the network call fails before you receive a response, you can use the stored ID to look up whether the order was created on the exchange side.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.