# Error Codes

> Every Tradavity Public API error code, mapped to its HTTP status and meaning.
> Source: https://help.tradavity.com/api-docs/error-codes
> Category: Core Concepts

---

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed input. `error.details` may include field-level info. |
| 401 | `unauthorized` | Missing or invalid key, or the user account is disabled / suspended. |
| 401 | `key_revoked` | Key was revoked. |
| 401 | `key_expired` | Key passed its expiry date. |
| 401 | `token_expired` | (Auto-sync) The broker token cannot be renewed. User must reconnect via the settings UI. |
| 403 | `forbidden_scope` | Authentication OK but the key lacks the required scope. |
| 404 | `not_found` | The resource does not exist or does not belong to you. Returned identically for both cases to prevent ID enumeration. |
| 405 | `method_not_allowed` | Wrong HTTP method. `error.details.allowed` lists what is accepted. |
| 409 | `idempotency_conflict` | Same Idempotency-Key reused with a different request body. |
| 409 | `duplicate_name` | Tag, tag category, account, strategy, copy group: name already exists. |
| 409 | `category_has_tags` | Cannot delete a tag category that still has tags. |
| 409 | `conflict` | Resource-specific conflict (e.g. copy group member already in another group). |
| 413 | `request_too_large` | Request body exceeds the size cap (1 MB JSON, 10 MB screenshot). |
| 413 | `limit_reached` | Storage quota exceeded on a screenshot upload. |
| 429 | `rate_limited` | Rate limit hit. Retry after `Retry-After` seconds. `X-RateLimit-Scope` indicates which window: `key`, `user`, `key-daily`, or `ip-preauth` (unauthenticated abuse). |
| 429 | `limit_reached` | Subscription cap hit (e.g. account count, strategy count, Pro-only feature without a Pro plan). |
| 500 | `internal_error` | Unexpected server-side problem. Include the `request_id` from `meta` when reporting. |
| 502 | `broker_api_error` | (Auto-sync) Upstream broker API returned an error. Retry later. |
| 503 | `deadlock_retry` | Two concurrent writes deadlocked. Retry after `Retry-After` (1 second). |