Skip to main content

API Error Codes & Common Failures

TVH endpoints return a small set of HTTP status codes plus a plaintext or JSON error body. This page maps the codes you'll actually see to causes and fixes, and lists the asymmetric cases where a 200 OK still means the trade failed.

TL;DR
  • 200 ≠ "trade executed" for the queued webhook. It means "signal accepted into the queue". Always check Activity Log for the execution outcome.
  • 400 Bad Request is the catch-all for webhook input problems — parsing, unknown user, validation. Inspect the body.
  • The webhook returns 400 for auth-equivalent failures (there is no 401 on the webhook).
  • Order rejection by the exchange (insufficient funds, postOnly would-cross, symbol filter violation) typically returns 200 OK at the HTTP layer but logs an error in Activity Log.

HTTP status code reference​

StatusWhereWhat it meansTypical cause
200 OKWebhookRequest accepted. Does not guarantee trade execution.Signal queued.
400 Bad RequestWebhookMalformed body, unknown user, validation failure.Inspect body for the cause. See Common 400 causes.
404 Not FoundWebhookRoute not found.Typo in URL. The webhook lives at /, not /api/ExecuteTradeSignal.
500 Internal Server ErrorWebhookUnhandled server-side failure.Auto-retried by the queued endpoint.
503 Service UnavailableRareBackend dependency unavailable.Auto-retried. Persistent 503 → support.

Common 400 causes​

400 on the webhook endpoint is the most common error and always carries a plaintext body. The exact strings:

BodyCauseFix
User not found. Token: <guid>The token field doesn't match any TVH account.Copy the token from TVH dashboard → Account → Settings. Watch for trailing whitespace.
user token was not setThe body parsed but token was empty.Add "token": "<guid>" to the JSON.
error while parsing trade signalThe body is not valid JSON, or contains fields TVH can't deserialize.Validate JSON in jsonlint.com. Check for trailing commas, unquoted keys, smart quotes.
Invalid trade command: <body>Body parsed but the resulting TradeCommand failed downstream validation.Inspect the full body in Activity Log. Usually a missing sizing field or an unknown orderType.
error while sending multiple trade commandsBatch payload parsed, but one of the children failed.Inspect the batch contents. The failing child is logged.
Unexpected error occured. Exception: <message>Unhandled exception in the receiver.Report to support with the exception text and approximate timestamp.

TVH-specific error scenarios​

Wrong symbol format​

The exchange returns "symbol not found" or an obscure 4xx. The HTTP webhook response is typically 200 OK (queued path) or a 400 with the exchange's raw message (classic path).

Fix: use the exchange's canonical pair format, not TradingView's display format. Examples in Trade Command → Core Parameters.

postOnly limit order rejected​

Sending a limit buy above (or sell below) the current price with postOnly: true will be rejected by most exchanges because it would cross the spread immediately. The response is 200 OK and the failure appears in Activity Log:

Order rejected: postOnly order would immediately match

Fix: place the limit on the correct side of the spread, or unset postOnly.

Token mismatch (User Token vs ApiKey name)​

The token field resolves to a user, but the apiKey field references a name that doesn't exist under that user. Webhook returns 200 OK (queued) or 400 (classic) with a body like:

ApiKey 'BinanceLive' not found for user

Fix: list the user's keys in TVH dashboard → API Keys. Names are case-sensitive.

Subscription expired​

Active subscription is required to trade with non-trial keys. Expired subscriptions cause:

  • Webhooks: 200 OK at HTTP layer + Activity Log entry "Subscription expired" + no exchange call.

Fix: renew in TVH dashboard → Subscription.

Order-execution failures with HTTP 200​

This is the most counter-intuitive class of failure. The queued webhook returned 200 OK (signal accepted into the queue), but the downstream queue worker encountered an exchange error and the trade never reached the order book.

Examples:

  • Insufficient funds: Insufficient USDT balance: needs 105.32, has 102.18
  • Symbol filter violation: qty 0.00123 below minQty 0.001 for BTCUSDT
  • API key permission missing: API-key has no permission for futures trading
  • IP not whitelisted on exchange: Invalid API-key, IP, or permissions for action

In all of these the HTTP response is 200 OK. The only authoritative status is the Activity Log entry.

Why 200 OK for exchange errors?

The queued endpoint hands the signal to a queue and returns immediately. The actual exchange call happens seconds later in a separate worker. By the time the exchange rejects the order, the HTTP request that triggered it is long gone. The Activity Log is the asynchronous result channel — always check it after a non-trivial signal.

Error body formats​

The two webhook variants emit slightly different body formats:

EndpointSuccess bodyError body
/ (queued)emptyplaintext error message
/api/ExecuteTradeSignalClassichuman-readable status stringplaintext error message

For Activity Log entries, the format is always plaintext with the original error chain preserved.

Diagnostic checklist​

When a webhook returns 200 but no trade happens:

  1. Activity Log — does the entry show the signal? If not, the queue worker never ran. Check the queued vs classic URL.
  2. Activity Log error string — is the message from TVH or from the exchange? Exchange-prefixed errors (Binance: ..., Bybit: ...) mean TVH made the call and the exchange refused.
  3. alertTimestamp dedup — was this triple already processed? Activity Log shows the original entry; the duplicate is silently dropped.
  4. API key permissions — does the key have futures / margin / withdrawal as needed?
  5. IP whitelist — see Getting Started → Webhook URLs & IP for the egress IP set the exchange must allow.

Cross-references​