Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tradewatch.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide helps you diagnose the most common integration failures across the TradeWatch REST and WebSocket APIs. Start with the error or symptom you see, then follow the recovery steps.

​
Quick checks

Before debugging a specific error, verify the basics:
  • Confirm you are using the correct base URL for the API you are calling.
  • Confirm your API key is present and has not been revoked.
  • Confirm the symbol and endpoint belong to the same asset class.
  • Confirm your account plan includes the feature you are trying to use.
  • Check the System Status page for active incidents.

​
Common HTTP errors

​
401 Unauthorized

What it usually means Your request did not include a valid API key, or the key could not be accepted. Common causes
  • The api-key value is missing.
  • The API key is misspelled, truncated, or contains extra whitespace.
  • The API key was revoked and replaced.
  • Your application is reading the wrong environment variable.
How to recover
  1. Generate or reveal the active key in the API keys dashboard.
  2. Verify the exact key value your application sends.
  3. Retry the request with a minimal test call.
  4. If the key is old or exposed, revoke it and create a new one.
Example 
curl "https://api.tradewatch.io/latest?base=USD&api-key=YOUR_API_KEY"

​
403 Forbidden

What it usually means The request is authenticated, but your account is not allowed to use that feature. Common causes
  • Your plan does not include the endpoint or data product.
  • Your plan does not include WebSocket access.
  • The requested feature is restricted to a higher tier.
How to recover
  1. Confirm your plan and entitlements in the dashboard.
  2. Compare the feature you need with your subscription.
  3. If needed, upgrade the plan or contact support.

​
404 Not Found

What it usually means The route or requested resource does not exist. Common causes
  • The path is incorrect.
  • The asset class is wrong for the endpoint.
  • The symbol is not supported.
  • The request is using an outdated route from an old integration.
How to recover
  1. Recheck the endpoint in the API reference.
  2. Confirm the symbol exists in the relevant Symbols catalog.
  3. Verify that the endpoint and symbol belong to the same product family.
  4. Retry with a known-good example from the docs.

​
429 Too Many Requests

What it usually means Your application exceeded one or more platform rate or connection limits. Common causes
  • Request bursts without throttling.
  • Aggressive polling for data better suited to WebSocket streaming.
  • Multiple services sharing the same IP and quota.
  • Automatic retries without backoff.
How to recover
  1. Stop sending immediate retries.
  2. Add exponential backoff with jitter.
  3. Reduce polling frequency where possible.
  4. Move real-time workloads to WebSocket if you need continuous updates.
  5. Review the Limits page.
Recommended retry pattern Use progressively longer delays after 429 responses. If your workload is sustained rather than bursty, lower the steady-state request rate instead of only retrying more slowly.

​
Common WebSocket issues

​
Connection closes immediately

What it usually means The handshake succeeded or partially succeeded, but the session could not stay open. Common causes
  • Missing or invalid api-key header.
  • Connecting to the wrong WebSocket URL.
  • Your plan does not include streaming access.
  • The service is unavailable during an incident or maintenance window.
How to recover
  1. Verify the WebSocket URL is wss://api.tradewatch.io/....
  2. Verify the api-key header is present and valid.
  3. Confirm WebSocket access is included in your plan.
  4. Check the System Status page.

​
Subscriptions succeed but no market data arrives

What it usually means Your connection is open, but the requested instruments are inactive or simply not producing updates at that moment. Common causes
  • Subscribing to the wrong channel for the instrument type.
  • Expecting continuous ticks for instruments that are currently inactive.
How to recover
  1. Confirm the channel matches the asset class you are subscribing to.
  2. Test with a small set of known, liquid symbols first.
  3. Keep the connection open long enough to observe updates.

​
Connection drops after running for a while

What it usually means The session was interrupted by network instability, client timeout handling, or platform-side protection. Common causes
  • Your client does not handle ping/pong correctly.
  • The client reconnects too aggressively after transient failures.
How to recover
  1. Make sure your client responds to ping frames with pong frames.
  2. Implement reconnect logic with exponential backoff.
  3. Re-send subscriptions after reconnecting.
  4. Log close codes and disconnect frequency so you can distinguish local network issues from server-side failures.

​
Invalid symbols

If an endpoint or subscription fails for only some instruments, invalid or unsupported symbols are the most likely cause. Common causes
  • Using EUR/USD when the API expects EURUSD
  • Mixing stock tickers with forex or crypto endpoints
  • Using a symbol that is not in the supported catalog
  • Using exchange-specific assumptions that do not match TradeWatch naming
How to recover
  1. Look up the instrument in the Symbols pages.
  2. Copy the symbol format exactly as documented.
  3. Test one symbol at a time before sending large batches.
  4. If a symbol used to work and no longer does, check the Support page and contact support with the exact symbol and endpoint.

​
Troubleshooting workflow

When an issue is unclear, use this sequence:
  1. Reproduce the issue with a minimal request or one-symbol WebSocket subscription.
  2. Confirm the API key, base URL, and endpoint path.
  3. Verify the symbol in the documentation.
  4. Check your plan entitlements.
  5. Check the System Status page.
  6. If the issue persists, contact support with the endpoint, symbol, timestamp, and full error response.

​
When to contact support

Contact support if:
  • A documented endpoint returns an unexpected 404
  • A valid API key consistently returns 401
  • You see repeated 429 responses even after throttling
  • Valid symbols subscribe successfully but never produce data
  • Disconnects continue after you implement ping/pong handling and reconnect backoff
Include the following in your ticket:
  • Endpoint or WebSocket channel
  • Symbol or symbols involved
  • Approximate timestamp of the failure
  • HTTP status code or WebSocket close behavior
  • Sanitized request example
  • Any response body or error payload