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:

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

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.

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.

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.

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.

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 endpoint before submitting the order, and cancel any unnecessary open orders to free up held funds.

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 for active incidents and retry once trading is re-enabled.

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 endpoint to retrieve the full list of valid, tradeable product IDs.

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.

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.

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.

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 for real-time market data instead of polling REST endpoints.

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.

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

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:

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) to determine the true state.

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"
        }
    }
}

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.