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