tastytradeDeveloper Docs

API Reference / Errors

Error reference

Errors return an error object with code and message. Branch on the code, not the message text, and back off on 429.

docUrl convention: every entry below has a stable anchor, so an error maps to a fixed documentation URL — /reference/errors#<code> (e.g. /reference/errors#401). Agents can construct it from an error's HTTP status or error.code to self-correct. A machine-readable list is at /errors.json.

Bad Request

Common causes

  • Malformed JSON, or a body that doesn't match the endpoint schema.
  • Missing required fields, or wrong types/param names (keys are dasherized).

Fix: Validate the request against the endpoint's schema in the API Reference. Ensure valid JSON and dasherized keys.

Unauthorized

Common causes

  • Missing `Authorization` header, or an expired/invalid access token (tokens last 15 minutes).
  • Invalid username/password at login.
  • Missing or malformed `User-Agent` header — tastytrade requires the format `<product>/<version>`; otherwise it returns 401.

Fix: Send a valid `Authorization: Bearer <token>` (refresh every 15 minutes) AND always set a `User-Agent` like `my-app/1.0`.

Forbidden

Common causes

  • Authenticated, but the token's scope or the account authority doesn't permit this action.

Fix: Check your OAuth scopes and the account's authority level for the operation.

Not Found

Common causes

  • Unknown resource — wrong account number, symbol, or order id.
  • Wrong base URL / environment (sandbox vs production).

Fix: Verify the path and identifiers, and confirm the environment: sandbox `api.cert.tastyworks.com` vs production `api.tastyworks.com`.

Unprocessable Entity

Common causes

  • The action is invalid in context. For orders, a rejection returns 422 with a reason in the response JSON's `error.message`.

Fix: Read `error.message`. For orders, run the dry-run first and fix the rejection reason before submitting.

Too Many Requests

Common causes

  • Request rate exceeded reasonable thresholds.

Fix: Back off exponentially and reduce request rate. For market data, use the DXLink streamer instead of polling. Separately (a related but distinct symptom): repeated failed logins trigger an IP block that surfaces as connection timeouts, not 429s — it typically lasts ~8 hours; contact api.support@tastytrade.com to be unblocked.

Server ErrorHTTP 5xx

Common causes

  • An unexpected error on tastytrade's side.

Fix: Retry with exponential backoff. If it persists, contact api.support@tastytrade.com with the request details.

`unauthorized`HTTP 401

Common causes

  • No valid access token. Access tokens last 15 minutes and must be sent on every request.

Fix: Generate an access token and include it in the `Authorization` header on every request.

`invalid_credentials`HTTP 401

Common causes

  • Wrong username/password at login — often caused by using sandbox credentials against production (or vice versa); each environment has separate credentials.

Fix: Confirm you're using the correct credentials for the environment you're hitting (sandbox vs production).

`unconfirmed_user`HTTP 401

Common causes

  • The user account has not completed confirmation/onboarding.

Fix: Ensure the (sandbox) customer/account is fully created and confirmed. See the FAQ, or contact api.support@tastytrade.com.

`not_permitted`HTTP 403

Common causes

  • Authenticated, but not authorized to access this resource — for example, requesting data for an account that belongs to a different customer. The message is `User not permitted access`.

Fix: Verify the account number belongs to the authenticated user and that your credentials permit the operation.

`preflight_check_failure`HTTP 422

Common causes

  • An order failed one or more preflight validations and was rejected. The specific failures are nested in `error.errors[]`, each with its own `code` and `message` (e.g. `cant_buy_for_credit`).

Fix: Read each entry in `error.errors[]` and fix the order accordingly. Run the dry-run endpoint first to catch rejections before submitting.

`cannot_update_order`HTTP 422

Common causes

  • Cancellation was requested for an order that is already in a terminal status, so it can no longer be cancelled. The message is `the order could not be cancelled`.

Fix: Fetch the order's current status before requesting cancellation; orders in a terminal status (e.g. `Filled`, `Cancelled`, `Rejected`) cannot be cancelled. See the Order Flow guide for terminal statuses.

`cant_buy_for_credit`HTTP 422

Common causes

  • A buy order was submitted with `"price-effect": "Credit"`, which is not allowed. This code appears nested in `error.errors[]` under a `preflight_check_failure`.

Fix: Set `price-effect` to `Debit` for orders that cost money to place and resubmit. Run the dry-run endpoint first to catch this before submitting.

Preflight errors and warnings

An order that fails preflight returns preflight_check_failure (HTTP 422) with each failure in error.errors[]. Entries marked warning are different: they never appear in that 422. They come back in data.warnings[] of a successful response (a dry-run or a placed order) and do not block the order. Branch on code; the message is shown as the order service returns it, with %{name} standing for a value filled in at runtime. Where several messages are listed under one code, the service returns that code with any of them.

This list is partial. Other preflight codes can be returned that are not listed here, so handle an unrecognised code by falling back to the message.

Account, approval and buying power

  • closing_only_check_failed error
    Account is set to closing only and this order has an opening leg.
  • restricted_position_check_failed error
    A portion of this position is frozen. This may be due to pending transfers. Please contact the trade desk if you have any questions.
  • restricted_symbol_for_foreign_customers error
    %{symbol} is a restricted symbol for customers residing outside of the USA.
  • margin_check_failed_with_flags error
    Account does not have sufficient buying power available for this order due to %{risk_flags}.
  • delta_risk_check_failed error
    Excessive risk - Consider an order that will reduce delta exposure.
  • net_liq_ratio_error error
    Cash balance cannot exceed 15 times net liq.
  • margin_check_failed error
    Your account does not have sufficient buying power available for this order. Please deposit funds or reduce the order size to place this.
  • risk_check_failed error
    Your account is not approved for spreads. Please check our help section to confirm the account types that support this.
    Your account is not approved for selling uncovered options. Please check our help section to confirm the account types that support this.
    Selling uncovered calls is not enabled for this account. Please check our help section to confirm the account types that support this.
    Account only approved for long equity positions
    Account cannot sell uncovered calls on this underlying
    Account cannot sell uncovered calls on underlyings with price below %{threshold}
  • short_sell_not_allowed error
    Your account is not approved for selling stock short. Please check our help section to confirm the account types that support this.

Price and market

  • cant_buy_for_credit error
    You cannot buy for a credit.
  • cant_sell_for_debit error
    You cannot sell for a debit.
  • zero_price_not_allowed error
    Order price is invalid for this trade. You cannot place an order with 0.00 price.
  • invalid_fractional_price warning
    Order price resolution must not be smaller than a penny.
  • invalid_order_price error
    Order price is invalid for this trade. Contact trade desk with any questions
  • invalid_price_increment error
    Price must be in increments of $%{increment} for this order.
  • limit_like_orders_require_price error
    Limit like orders require a price.
  • order_limit_price_overflow error
    Order limit price exceeds the maximum price allowed. Please reduce the price to proceed.
  • order_must_omit_price error
    This order can not be submitted with an associated price.
  • spread_market_order_check_failed error
    Orders with 2 or more legs cannot be placed as "Market" orders.
  • spread_width_price_check_failed error
    Order price is greater than spread width.
  • unfavorable_price error
    Unfavorable price - Consider limit at or better than strike
  • marketable_limit_price_error error
    No suitable price found for the marketable limit order. Please consider routing a limit order.
  • marketable_limit_instrument_not_allowed error
    Marketable limit orders can only be routed for multi-leg options and covered stock.
  • no_bid_or_ask warning
    One or more legs in this order do not have a bid or ask.
  • no_quote_found error
    Unable to route order. No quote found.

Order structure

  • cash_settled_equity_invalid error
    Orders may not contain an equity leg for a cash settled index. (There is no actual instrument to trade).
  • duplicate_order_leg_symbols error
    Order legs cannot have duplicate symbols.
  • illegal_buy_and_sell_on_same_symbol error
    Cannot buy and sell against the same symbol.
  • invalid_combined_option_stock_amount error
    Order contains equity leg and more than one option leg
  • multiple_equity_legs_invalid error
    Orders may not have multiple equity legs.
  • invalid_symbol error
    This order contains a leg with an invalid symbol.
  • order_leg_must_have_quantity error
    Order Legs for this order type must have a quantity.
  • cannot_close_more_than_existing_position error
    You cannot close more than %{quantity} for %{symbol}.
  • closing_with_no_position warning
    You cannot route a closing order without an existing position to close. This order will be updated to a %{open_close} order when routed.
    Fractional equity and cryptocurrency orders can also return this code as an error, with a different message.
  • closing_with_no_position_error error
    You cannot route a closing order without an existing position to close.
  • too_close_to_expiration error
    Sell to open orders cannot be sent %{interval} prior to market close on day of expiration.
  • qty_greater_than_zero error
    Orders with a leg remaining must have a remaining quantity greater than zero.
  • closing_only error
    %{symbol} is currently set to closing only. Only closing trades may be submitted at this time.
    This expiration cycle for %{symbol} is now closing only. Please close your position or roll it to the active expiration
  • duplicate_closing_order error
    You already have a closing order for %{symbol} which must be canceled before this order can be routed.
    Only fractional equity and cryptocurrency orders return this code. Other orders get cannot_close_against_more_than_existing_position with the same message instead, and fractional equity and cryptocurrency orders can return that code too, so handle both.
  • cannot_close_against_more_than_existing_position error
    You already have a closing order for %{symbol} which must be canceled before this order can be routed.
  • illegal_open_or_close_against_long_position warning
    You cannot %{action} against a %{direction} position. This order will be updated to a %{open_close} order when routed.
    Dry-run only. An order that sets advanced-instructions.strict-position-effect-validation gets the _error code instead, as an error.
  • illegal_open_or_close_against_short_position warning
    You cannot %{action} against a %{direction} position. This order will be updated to a %{open_close} order when routed.
    Dry-run only. An order that sets advanced-instructions.strict-position-effect-validation gets the _error code instead, as an error.
  • illegal_open_or_close_against_long_position_error error
    You cannot %{action} against a %{direction} position.
    Returned only when the order sets advanced-instructions.strict-position-effect-validation.
  • illegal_open_or_close_against_short_position_error error
    You cannot %{action} against a %{direction} position.
    Returned only when the order sets advanced-instructions.strict-position-effect-validation.
  • invalid_action error
    Opening orders with non standard options are not supported.

Complex orders

  • invalid_complex_complexity error
    Complex order limit hit for %{underlying_symbol}
  • invalid_complex_structure error
    Complex order structure is invalid
  • invalid_complex_tif error
    A complex order with a GTC trigger order may not have dependent orders with a time in force of Day
  • invalid_complex_underlying error
    Complex orders must share an underlying symbol
  • invalid_complex_fractional error
    Complex orders for this instrument type cannot have fractional quantities
  • invalid_complex_cryptocurrency error
    Only conditional complex orders are supported for this instrument type
  • invalid_triggered_order_price error
    Order price is invalid for this trade.
  • pairs_trade warning
    Pairs orders have additional execution risk as each order routes separately with price type market.

Futures

  • cfe_stop_future_order_not_allowed error
    Stop market orders for %{underlying_symbol} are not allowed by the CFE.
  • cfe_market_order_not_allowed error
    Market orders only allowed during regular trading hours by the CFE.
  • cfe_multiple_legs_not_allowed error
    Multi leg orders are not supported for CFE products.
  • future_option_too_close_to_expiration error
    Future option opening trades cannot be placed %{interval} prior to market close on day of expiration.
  • insufficient_net_liquid_value error
    A minimum net liquidating value of $%{net_liq} is required to open this new futures positions.
  • invalid_futures_fractional_price error
    Fractionally price futures must be submitted in decimal format.
  • invalid_strategy error
    This strategy type is not supported. Try legging in.
  • instrument_not_tradeable error
    This is not a tradeable product.
  • only_limit_future_spread_orders_allowed error
    Only limit orders are allowed for future spreads.
  • stop_future_option_order_not_allowed error
    Stop market and stop limit future option orders are not allowed.
  • unable_to_accept_cancel error
    Unable to cancel order. %{instrument_collection} markets are not currently accepting them.
  • unable_to_cancel_past_stops_trading_at error
    Unable to cancel order. %{instrument} is no longer trading.
  • order_not_allowed error
    This order cannot be placed right now. Contact trade desk with any questions
  • futures_not_allowed error
    Your account is not approved for futures trading. Please enable futures trading to place this trade.

Time in force

  • invalid_gtd_expiration_date error
    The GTD date is past the option expiration.
  • past_gtd_date error
    GTD date cannot be in the past.
  • tif.not_routable error
    Order cannot be routed at this time.
  • tif.day_invalid_intersession error
    Day orders will be accepted after 3:15pm CT. Consider EXT to route now.
  • tif.next_valid_session warning
    Your order will begin working during next valid session.
    Also returned in warnings[] when the order is placed, not only on a dry-run.
  • tif.futures_invalid error
    This time in force value is not supported for futures trades.
  • tif.futures_session_not_active error
    The Futures trading session is not currently active.
  • tif.cryptocurrency_invalid error
    This time in force value is not supported for cryptocurrency trades with this order type.
  • tif_single_leg_equities_only error
    Orders with a time in force of %{time_in_force} must only include a single Equity instrument.
  • tif_limit_orders_only error
    Orders with a time in force of %{time_in_force} must be Limit or Stop Limit orders.
  • tif_no_after_hours_orders error
    EXT orders can only be routed between %{start_time} and %{end_time} Central, and on market half days between %{start_time} and %{half_day_end_time} Central. EXT trading is closed on market holidays.
    Overnight orders can only be routed during market days or during the overnight hours prior to a market day.
  • tif_no_after_hours_opening_market_orders error
    Opening market orders not allowed when market closed.
  • tif_no_stop_market_gtc_options error
    Stop Market Equity Option orders cannot be GTC or GTD

Limits

  • order_limit_check_failed error
    Order size exceeds the limit. Contact the trade desk to increase your limits.
  • position_limit_check_failed error
    Resulting position size exceeds the limit. Contact the trade desk to increase your limits.
  • underlying_opening_order_limit_check_failed error
    Number of opening orders for underlying exceeds the limit. Contact the trade desk to increase your limits.