docs(errors): align error code reference with canonical Go list

Replace per-page error tables with the authoritative 19 HTTP + 6
WebSocket-frame codes now defined in sharp-api-go/pkg/errcodes.

Remove fabricated codes that never actually shipped: forbidden,
unknown_type, stream_limit_exceeded. Replace bad_request and
invalid_request (deprecated, collapsed server-side) with
validation_error. Document unauthorized, invalid_api_key, and
invalid_token as three distinct auth-failure codes covering admin
bearer, user API key, and Clerk session paths respectively.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

content/en/api-reference/account-keys.mdx

@@ -275,7 +275,7 @@ print(f"Deleted key: {result['key_id']}")
 ```json
 {
   "error": {
-    "code": "invalid_request",
+    "code": "validation_error",
     "message": "Cannot delete the API key used to authenticate this request",
     "docs": "https://docs.sharpapi.io/en/api-reference/account-keys"
   }

content/en/api-reference/conventions.mdx

@@ -100,7 +100,9 @@ Every non-2xx response returns a single `error` object.
 
 ### Common error codes
 
-`missing_api_key`, `invalid_api_key`, `validation_error`, `invalid_request`, `tier_restricted`, `rate_limited`, `too_many_streams`, `not_found`, `upstream_error`, `internal_error`.
+`missing_api_key`, `invalid_api_key`, `validation_error`, `tier_restricted`, `rate_limited`, `too_many_streams`, `not_found`, `upstream_error`, `internal_error`.
+
+See the full list (19 HTTP codes + 6 WebSocket frame codes, with HTTP statuses) in [API Overview → Error Codes](/en/api-reference/overview#error-codes). `bad_request` and `invalid_request` are deprecated — both were collapsed into `validation_error`.
 
 ## Timestamps
 

content/en/api-reference/deeplinks.mdx

@@ -145,7 +145,7 @@ To get the final sportsbook URL, either follow the redirect (`GET https://api.sh
 ```json
 {
   "error": {
-    "code": "bad_request",
+    "code": "validation_error",
     "message": "ids array required"
   }
 }
@@ -155,7 +155,7 @@ To get the final sportsbook URL, either follow the redirect (`GET https://api.sh
 ```json
 {
   "error": {
-    "code": "bad_request",
+    "code": "validation_error",
     "message": "Maximum 500 IDs per batch"
   }
 }

content/en/api-reference/events.mdx

@@ -301,7 +301,7 @@ data = response.json()
 ```json
 {
   "error": {
-    "code": "invalid_request",
+    "code": "validation_error",
     "message": "Invalid date format. Use YYYY-MM-DD.",
     "docs": "https://docs.sharpapi.io/en/api-reference/events"
   }

content/en/api-reference/odds-batch.mdx

@@ -39,7 +39,7 @@ The maximum number of events per batch request depends on your tier:
 | **Enterprise** | 100 |
 
 <Callout type="warning">
-Exceeding the batch limit for your tier will return a `400 invalid_request` error. Split large requests into multiple batches if needed.
+Exceeding the batch limit for your tier will return a `400 validation_error` error. Split large requests into multiple batches if needed.
 </Callout>
 
 ## Example Requests
@@ -207,7 +207,7 @@ X-Request-Id: req_batch_abc123
 ```json
 {
   "error": {
-    "code": "invalid_request",
+    "code": "validation_error",
     "message": "Batch limit exceeded. Your tier (hobby) allows 10 events per batch, but 25 were requested.",
     "docs": "https://docs.sharpapi.io/en/api-reference/odds-batch"
   }
@@ -218,7 +218,7 @@ X-Request-Id: req_batch_abc123
 ```json
 {
   "error": {
-    "code": "invalid_request",
+    "code": "validation_error",
     "message": "The 'event_ids' field is required and must be a non-empty array of event IDs.",
     "docs": "https://docs.sharpapi.io/en/api-reference/odds-batch"
   }

content/en/api-reference/odds-delta.mdx

@@ -40,7 +40,7 @@ Use the `server_time` from each response as the `since` value for your next requ
 | `offset` | integer | 0 | Pagination offset |
 
 <Callout type="warning">
-The `since` parameter is **required**. Omitting it returns a `400 invalid_request` error.
+The `since` parameter is **required**. Omitting it returns a `400 validation_error` error.
 </Callout>
 
 ## Example Requests
@@ -164,7 +164,7 @@ X-Request-Id: req_delta_abc123
 ```json
 {
   "error": {
-    "code": "invalid_request",
+    "code": "validation_error",
     "message": "The 'since' parameter is required for the delta endpoint",
     "docs": "https://docs.sharpapi.io/en/api-reference/odds-delta"
   }

content/en/api-reference/overview.mdx

@@ -313,14 +313,47 @@ All odds are returned as flat fields on each odds object:
 
 ## Error Codes
 
+The canonical list of error codes emitted by the API. The string in `error.code` is the stable contract — check it rather than the prose `message`.
+
+### HTTP error codes
+
+Emitted in REST responses.
+
 | Code | HTTP Status | Description |
 |------|-------------|-------------|
-| `unauthorized` | 401 | Missing or invalid API key |
-| `forbidden` | 403 | Feature requires higher tier |
-| `rate_limited` | 429 | Too many requests |
-| `tier_restricted` | 403 | Endpoint not available on your tier |
-| `invalid_request` | 400 | Malformed request parameters |
+| `missing_api_key` | 401 | No API key supplied via `X-API-Key`, `?api_key=`, or `Authorization: Bearer` |
+| `invalid_api_key` | 401 | API key was supplied but is not recognized |
+| `expired_api_key` | 401 | API key has expired — generate a new one in the dashboard |
+| `disabled_api_key` | 401 | API key is disabled, usually because the subscription lapsed |
+| `unauthorized` | 401 | Bearer-token auth failed on admin or `/api/v1/monitoring/*` endpoints (distinct from `invalid_api_key`) |
+| `invalid_token` | 401 | Clerk session token failed verification (dashboard-only endpoints) |
+| `tier_restricted` | 403 | Endpoint or feature is not available on your tier — response includes `tier` and `required_tier` |
 | `not_found` | 404 | Resource not found |
+| `method_not_allowed` | 405 | HTTP method is not supported on this route |
+| `gone` | 410 | Event has ended or expired — use `/api/v1/events` for current events |
 | `unknown_endpoint` | 410 | Wrong API path — response includes `correct_endpoint` with the right route (e.g. `/api/v1/arbitrage` → `/api/v1/opportunities/arbitrage`) |
-| `upstream_error` | 502 | Temporary data fetch issue |
-| `internal_error` | 500 | Server error |
+| `validation_error` | 400 | Request body or query parameters failed validation |
+| `rate_limited` | 429 | Per-minute request rate limit exceeded — response includes `retry_after` |
+| `concurrent_request_cap` | 429 | Too many in-flight requests for your tier — reduce parallelism or upgrade |
+| `too_many_streams` | 429 | Maximum concurrent SSE or WebSocket streams exceeded for this API key |
+| `backpressure` | — | Emitted as an SSE `event: error` (not an HTTP status) when the client cannot keep up; server then closes the stream |
+| `upstream_error` | 502 | Temporary issue reaching an upstream sportsbook or auth provider |
+| `service_unavailable` | 503 | A required service (e.g. key management) is not configured or is offline |
+| `internal_error` | 500 | Unexpected server error — retry with backoff and contact support with `X-Request-Id` if it persists |
+
+<Callout type="info">
+`bad_request` and `invalid_request` are **deprecated** — both were collapsed into `validation_error`. Clients that match on the old strings should add `validation_error` to their error map.
+</Callout>
+
+### WebSocket frame error codes
+
+Emitted only inside `{"type": "error", "code": "..."}` frames on an open WebSocket connection. They describe client-protocol mistakes and do not correspond to an HTTP status.
+
+| Code | Meaning |
+|------|---------|
+| `invalid_message` | Frame could not be parsed as JSON or did not match the expected shape |
+| `unknown_message_type` | `type` field is not one of the documented values (`auth`, `subscribe`, `filter`, `refresh_token`, `ping`) |
+| `missing_token` | `auth` or `refresh_token` frame did not include a `token` field |
+| `missing_channels` | `subscribe` frame did not include a non-empty `channels` array |
+| `not_authenticated` | Frame requires an authenticated session (sent `subscribe`, `filter`, or `refresh_token` before `auth`) |
+| `already_authenticated` | Client sent a second `auth` frame after the first one succeeded |

content/en/api-reference/stream.mdx

@@ -519,7 +519,7 @@ Each open SSE connection counts as one stream against your limit.
 | Enterprise | Custom |
 
 <Callout type="warning">
-Exceeding your stream limit returns a `429` error with code `stream_limit_exceeded`. Close unused streams before opening new ones.
+Exceeding your stream limit returns a `429` error with code `too_many_streams`. Close unused streams before opening new ones.
 </Callout>
 
 ### Managing Streams
@@ -546,10 +546,10 @@ These close the connection. Handle them in `onerror`:
 
 | Error Code | HTTP Status | Description | Resolution |
 |------------|-------------|-------------|------------|
-| `stream_limit_exceeded` | 429 | Too many concurrent streams | Close unused streams |
+| `too_many_streams` | 429 | Too many concurrent streams | Close unused streams |
 | `tier_restricted` | 403 | Streaming not available on your tier | Add WebSocket add-on |
-| `unauthorized` | 401 | Invalid API key | Check your API key |
-| `invalid_request` | 400 | Invalid filter parameters | Check query params |
+| `invalid_api_key` | 401 | API key missing or invalid | Check your API key |
+| `validation_error` | 400 | Invalid filter parameters | Check query params |
 
 ## Best Practices
 

content/en/api-reference/websocket.mdx

@@ -567,11 +567,24 @@ Error notification. The connection may remain open (for non-fatal errors) or clo
 {
   "type": "error",
   "seq": 152,
-  "code": "unknown_type",
+  "code": "unknown_message_type",
   "message": "Unknown message type: foobar"
 }
 ```
 
+The WebSocket layer emits a small, fixed set of frame-level error codes for client-protocol mistakes. They are distinct from the HTTP error codes returned by REST endpoints.
+
+| Code | Meaning |
+|------|---------|
+| `invalid_message` | Frame could not be parsed as JSON or did not match the expected shape |
+| `unknown_message_type` | `type` field is not one of `auth`, `subscribe`, `filter`, `refresh_token`, `ping` |
+| `missing_token` | `auth` or `refresh_token` frame did not include a `token` field |
+| `missing_channels` | `subscribe` frame did not include a non-empty `channels` array |
+| `not_authenticated` | Sent `subscribe`, `filter`, or `refresh_token` before `auth` succeeded |
+| `already_authenticated` | Client sent a second `auth` frame after the first one succeeded |
+
+WebSocket frames may also carry the HTTP-style `invalid_api_key`, `tier_restricted`, and `too_many_streams` codes — these cause the server to close the connection after the frame is sent. See [API Overview → Error Codes](/en/api-reference/overview#error-codes) for the full list.
+
 ## Close Codes
 
 | Code | Meaning | Resolution |

content/en/authentication.mdx

@@ -134,16 +134,22 @@ Authenticated requests receive higher rate limits based on your subscription tie
 
 ## Error Codes
 
+Auth-related codes you'll see most often. For the full list of 19 HTTP codes plus the 6 WebSocket frame codes, see [API Overview → Error Codes](/en/api-reference/overview#error-codes).
+
 | Code | HTTP Status | Description |
 |------|-------------|-------------|
-| `unauthorized` | 401 | API key missing or invalid |
-| `forbidden` | 403 | Feature requires higher tier |
-| `rate_limited` | 429 | Too many requests |
-| `tier_restricted` | 403 | Endpoint not available on your tier |
-| `invalid_request` | 400 | Malformed request parameters |
-| `not_found` | 404 | Resource not found |
-| `upstream_error` | 502 | Temporary issue fetching data |
-| `internal_error` | 500 | Server error |
+| `missing_api_key` | 401 | No API key was supplied |
+| `invalid_api_key` | 401 | API key was supplied but is not recognized |
+| `expired_api_key` | 401 | API key has expired |
+| `disabled_api_key` | 401 | API key is disabled, usually because the subscription lapsed |
+| `unauthorized` | 401 | Bearer-token auth failed on admin or monitoring endpoints (distinct from `invalid_api_key`) |
+| `invalid_token` | 401 | Clerk dashboard session token failed verification |
+| `tier_restricted` | 403 | Endpoint or feature not available on your tier |
+| `rate_limited` | 429 | Too many requests — see `retry_after` |
+| `too_many_streams` | 429 | Maximum concurrent SSE / WebSocket connections reached |
+| `validation_error` | 400 | Malformed request parameters (replaces the deprecated `bad_request` / `invalid_request`) |
+| `upstream_error` | 502 | Temporary issue reaching upstream |
+| `internal_error` | 500 | Unexpected server error |
 
 ### Error Response Format