> ## 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.

# Errors & Troubleshooting

> Diagnose common TradeWatch API issues including 401, 403, 404, 429, invalid symbols, and WebSocket disconnects.

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](/platform/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](https://dash.tradewatch.io/api-keys).
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**

```bash theme={null}
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](https://dash.tradewatch.io/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](/symbols/introduction) 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](/platform/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](/platform/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](/symbols/introduction) 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](/platform/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](/platform/status) page.
6. If the issue persists, contact [support](https://dash.tradewatch.io/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