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 and validation. Inspect the body.
• An unknown or outdated token on the queued trade webhook gives 200 OK, and TVH drops the signal. The classic trade webhook answers 401 Unauthorized with the body Unknown webhook token.. See Unknown or outdated token.
• The queued trade webhook never returns 401. It returns 400 when the body has no token or cannot be parsed. A token that is present but unknown is not an error at the HTTP layer there: the answer is 200 OK.
• Endpoints that return data answer an unknown token with an error status. The trade host data functions return 400, the Trading Power Tool endpoints return 401.
• 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

Status	Where	What it means	Typical cause
200 OK	Webhook	Request accepted. Does not guarantee trade execution.	Signal queued, or the queued webhook dropped the signal because the token is unknown.
400 Bad Request	Webhook	Malformed body, validation failure.	Inspect body for the cause. See Common 400 causes.
401 Unauthorized	Classic webhook, Trading Power Tool endpoints	Unknown or outdated webhook token (classic). Unknown, empty or missing webhook token (Trading Power Tool).	See Unknown or outdated token and Trading Power Tool endpoints.
403 Forbidden	Trading Power Tool endpoints	The token is your user id (token not rotated yet).	Rotate the token first. See Trading Power Tool endpoints.
404 Not Found	Webhook	Route not found.	Typo in URL. The webhook lives at /, not /api/ExecuteTradeSignal.
429 Too Many Requests	Trading Power Tool endpoints	Rate limit: 30 calls per minute per token, 60 calls per minute per IP.	Wait one minute.
500 Internal Server Error	Webhook	Unhandled server-side failure.	Auto-retried by the queued endpoint.
503 Service Unavailable	Rare	Backend 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:

Body	Cause	Fix
user token was not set	The body parsed but token was empty.	Add "token": "<guid>" to the JSON.
error while parsing trade signal	The 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. If the token is valid, the Activity Log shows Invalid trade command: <excerpt>, the token shows as <redacted>.
error while sending multiple trade commands	Batch 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.

Unknown or outdated token

The response depends on the endpoint:

Endpoint	Response for an unknown token
Queued trade webhook (/)	200 OK with an empty body. TVH drops the signal.
Classic trade webhook (/api/ExecuteTradeSignalClassic)	401 Unauthorized with the body Unknown webhook token.. The answer is the same for an unknown and an outdated token. No trade starts.
Trade host data functions (GetBalance, GetPositionsAndOrders, CancelOrder, EditOrder on the Azure Functions host) and the MT5 EA	400 Bad Request with the body Unknown webhook token.
Trading Power Tool endpoints (/api/Extension/v2/... on www.tv-hub.org)	401 Unauthorized with the body Unknown webhook token.

TradingView shows no error for a signal that the queued webhook drops. If the token is your previous token (up to 6 months old), TVH writes this line into your Activity Log, at most once per day:

Signal rejected: outdated webhook token. Copy the new token from Settings.

Fix: copy the current Webhook Token from TVH dashboard → Account → Settings into the alert. Watch for trailing whitespace. See Rotate the token after a leak.

Trading Power Tool endpoints

The Trading Power Tool extension reads API keys, signal sources, balance and Activity Log lines from www.tv-hub.org/api/Extension/v2/.... It sends the webhook token in the X-Webhook-Token request header, never in the URL. All answers carry Cache-Control: no-store.

Status	Body	Cause	Fix
401 Unauthorized	Unknown webhook token.	The header is missing or empty, or no account has this token.	Copy the current token from Account → Settings.
403 Forbidden	Rotate your webhook token in the TvHub settings to use the extension.	The token equals your user id. Accounts that never rotated still have this legacy form. The trade webhook accepts it, the extension endpoints do not.	Rotate the token in Account → Settings, then paste the new token into the extension and into your alerts.
429 Too Many Requests	no fixed body	More than 30 calls per minute with one token, or more than 60 calls per minute from one IP.	Wait one minute.

The old routes with the user id in the path (GetApiKeys/{id}, GetBalance/{id}/..., GetCopyTradeSources/{id}, GetLogs/{id}) return 410 Gone.

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

Endpoint	Success body	Error body
/ (queued)	empty	plaintext error message
/api/ExecuteTradeSignalClassic	human-readable status string	plaintext 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

• Activity Log location and filtering: TVH dashboard → Activity Log
• Exchange-specific error mappings: Exchanges
• Common pitfalls: Trade Command → Gotchas