qzl
59 lines
3.7 KiB
Markdown
59 lines
3.7 KiB
Markdown
# HTTP Error Codes
|
|
|
|
This document is the source of truth for backend RFC7807 `code` values consumed by frontend.
|
|
|
|
## Auth
|
|
|
|
| code | status | meaning | frontend handling |
|
|
|---|---:|---|---|
|
|
| `AUTH_SERVICE_UNAVAILABLE` | 503 | Auth upstream unavailable | Show retry message and allow retry |
|
|
| `AUTH_TOO_MANY_REQUESTS` | 429 | OTP request throttled | Show wait message |
|
|
| `AUTH_VERIFICATION_CODE_INVALID` | 401 | Invalid OTP code | Prompt user to re-enter code |
|
|
| `AUTH_REFRESH_TOKEN_INVALID` | 401 | Invalid/expired refresh token | Clear local session and return login |
|
|
| `AUTH_REFRESH_TOKEN_MISSING` | 401 | Refresh token missing on logout | Treat as local logout and clear session |
|
|
| `AUTH_USER_NOT_FOUND` | 404 | User not found | Show not-found message where applicable |
|
|
|
|
## Agent Points
|
|
|
|
| code | status | meaning | frontend handling |
|
|
|---|---:|---|---|
|
|
| `POINTS_INSUFFICIENT_BALANCE` | 402 | Not enough points to start this run | Show recharge/insufficient-points prompt |
|
|
|
|
## Agent Session
|
|
|
|
| code | status | meaning | frontend handling |
|
|
|---|---:|---|---|
|
|
| `AGENT_SESSION_RUN_LIMIT_EXCEEDED` | 409 | Session already reached max run count (start + 1 follow-up) | Show run-limit message and require starting a new session |
|
|
| `AGENT_RUNTIME_MODE_INVALID` | 422 | Missing or invalid `forwardedProps.runtime_mode` in run request | Show invalid-request message and retry from current page |
|
|
| `AGENT_DIVINATION_PAYLOAD_REQUIRED` | 422 | Missing required `forwardedProps.divinationPayload` in run request | Prompt user to restart casting flow and resubmit |
|
|
| `AGENT_OUTPUT_DIVINATION_INVALID` | 422 | Worker output contains invalid `divination_derived` payload shape | Show generic history parse error and suggest retrying latest run |
|
|
| `AGENT_SESSION_ID_INVALID` | 422 | Invalid session/thread id format | Show invalid-session message and force refresh history |
|
|
| `AGENT_SESSION_NOT_FOUND` | 404 | Session does not exist (including follow-up on non-existing thread) | Show session-not-found message and refresh history |
|
|
| `AGENT_AUDIO_UNSUPPORTED_FORMAT` | 400 | Audio format is not accepted by transcribe endpoint | Show format hint and ask user to retry with wav audio |
|
|
| `AGENT_AUDIO_TOO_LARGE` | 400 | Audio file exceeds transcribe size limit | Show size-limit message and ask user to shorten audio |
|
|
| `AGENT_AUDIO_EMPTY` | 400 | Uploaded audio payload is empty | Show retry hint and keep input unchanged |
|
|
| `AGENT_ASR_UNAVAILABLE` | 502 | Upstream ASR service unavailable | Show retry message and allow fallback to text input |
|
|
|
|
## Profile
|
|
|
|
| code | status | meaning | frontend handling |
|
|
|---|---:|---|---|
|
|
| `PROFILE_PAYLOAD_INVALID` | 422 | Profile update payload invalid (length/type/empty constraints) | Highlight invalid fields and block submit |
|
|
| `PROFILE_NOT_FOUND` | 404 | User profile row missing | Show retry and optionally trigger profile bootstrap |
|
|
| `PROFILE_DELETE_FAILED` | 502 | Backend failed to complete account hard deletion | Show delete-failed message and allow retry |
|
|
|
|
## Avatar
|
|
|
|
| code | status | meaning | frontend handling |
|
|
|---|---:|---|---|
|
|
| `AVATAR_FILE_INVALID` | 422 | Avatar mime type or size is invalid | Show file validation hint and ask user to pick another image |
|
|
| `AVATAR_PATH_SCOPE_INVALID` | 422 | Avatar path does not belong to current user scope | Show generic security error and force refresh |
|
|
| `AVATAR_SIGNED_URL_FAILED` | 502 | Backend failed to generate avatar signed upload URL | Show retry toast and keep previous avatar |
|
|
| `AVATAR_UPLOAD_FAILED` | 502 | Backend failed to upload avatar bytes to storage | Show retry toast and keep previous avatar |
|
|
|
|
Compatibility strategy:
|
|
|
|
- Additive changes only for new codes.
|
|
- Existing codes must keep semantic meaning.
|
|
- Frontend must map by `code`, not by `detail` text.
|