# Troubleshoot Authentication and Access

> Diagnose OptionData API key, subscription, rate-limit, query-width, timeout, and WebSocket handshake failures without exposing credentials.

Use the HTTP status, stable error code, and request type to separate authentication problems from entitlement, rate-limit, and query-shape problems.

## Start with this checklist

1. Confirm you can sign in to the intended OptionData account.
2. Confirm the qualification survey is complete.
3. Open [Billing](/billing) and verify the Pro subscription is `trialing` or `active`.
4. Copy the current key from [API Key](/api_key).
5. Ensure the application is using that current key—not a value cached before regeneration.
6. Test one small HTTP request before testing a long-running client.

![Annotated OptionData API Key page showing the legacy-key warning and the replacement key area](/docs/troubleshoot-api-access/access-warning-annotated.png)

*A visible legacy-key warning is a configuration problem to fix before investigating endpoint behavior.*

## HTTP status guide

| Status | Meaning | Recommended action |
|---|---|---|
| `400` | Request validation or public SQL guard failed | Correct body fields, dates, filters, or SQL |
| `401` | Key missing, malformed, stale, or not owned by the current account | Recopy the key and check the bearer header |
| `403` | Customer recognized but not entitled | Review trial/subscription status |
| `404` | Exact Market Structure root or dated snapshot not found | Check the root and effective date |
| `422` | Historical SQL or Option Chain request exceeded a guardrail | Narrow date, symbol, expiration, or strike scope |
| `429` | Rate or connection limit exceeded | Honor `Retry-After` and back off |
| `504` | Query timed out | Split the request into smaller windows |
| `500` | Unexpected service failure | Retry once, then contact support with the request reference if supplied |

## WebSocket handshake guide

WebSocket authentication is decided during the HTTP upgrade:

- `101 Switching Protocols`: authentication and upgrade succeeded.
- `401`: token missing, invalid, or stale.
- `403`: recognized token without active/trialing entitlement.
- `429`: connection limit reached; keep existing connections open and honor the retry delay.

A listening port or successful DNS lookup does not prove WebSocket authentication. The `101` upgrade is the acceptance signal.

During closed market hours, a successful connection may receive no new live trades. Check the upgrade separately from market activity.

## After regenerating a key

The previous portal key stops working immediately. Update every deployment environment and restart consumers. Verify both:

1. One authenticated HTTP `200` response.
2. One WebSocket `101` upgrade.

## Contact support safely

Send:

- account email
- endpoint and approximate timestamp
- HTTP status and stable error code
- request reference ID, if the server returned one
- final four characters of the key only, if identification is necessary

Never send the complete API key, card number, bank details, ClickHouse password, or raw authorization header.