qzl
3f3d613d99
- 后端: 新增 notifications/user_notifications 表迁移及 ORM 模型
- 后端: 实现 schema/repository/service/router 全套通知 API
- GET /api/v1/notifications (列表+游标分页)
- GET /api/v1/notifications/unread-count
- PATCH /api/v1/notifications/{id}/read (幂等)
- PATCH /api/v1/notifications/mark-all-read (幂等)
- 后端: payload 使用 Pydantic discriminated union (none/open_route/open_url)
- 后端: 19 个单元测试全部通过
- Flutter: 通知 feature 完整实现 (models/apis/repositories/bloc/UI)
- Flutter: Home 页通知按钮接入真实页面，显示未读 badge
- Flutter: 14 个测试全部通过
- 协议文档: notification-inbox-protocol.md 及错误码注册
6.9 KiB
6.9 KiB
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 |
AUTH_UNAUTHORIZED |
401 | Missing or invalid auth credentials | Force logout and redirect to login |
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 message count (2 user messages per session: initial divination + 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_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_USER_ID_INVALID |
422 | Invalid user id in request context | Show invalid-request message |
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 |
AGENT_PAYLOAD_INVALID |
422 | Parsed run input payload is invalid | Show invalid-request message and retry from current page |
AGENT_RUN_INPUT_INVALID |
422 | Run request body fails validation | Show invalid-request message and retry |
AGENT_RUN_MESSAGES_INVALID |
422 | Run request messages contract violation | Show invalid-request message and retry |
AGENT_INVALID_RUN_ID |
422 | Invalid or missing runId query parameter |
Show invalid-request message and retry |
AGENT_INVALID_LAST_EVENT_ID |
422 | Invalid Last-Event-ID header format |
Retry without the header |
AGENT_SSE_CONNECTION_LIMIT |
429 | Too many concurrent SSE connections per user | Show connection-limit message and reduce concurrent streams |
AGENT_FORBIDDEN |
403 | User does not own the session resource | Force refresh and show unauthorized message |
AGENT_ATTACHMENT_EMPTY |
422 | Uploaded attachment payload is empty | Show retry hint and keep input unchanged |
AGENT_ATTACHMENT_TOO_LARGE |
413 | Attachment file exceeds size limit | Show size-limit message and ask user to use smaller file |
AGENT_ATTACHMENTS_TOO_MANY |
422 | Too many attachments in single message | Show attachment limit message |
AGENT_ATTACHMENT_UNSUPPORTED_TYPE |
422 | Attachment mime type is not supported | Show unsupported type message |
AGENT_ATTACHMENT_UPLOAD_FAILED |
502 | Backend failed to upload attachment to storage | Show retry toast |
AGENT_ATTACHMENT_STORAGE_UNAVAILABLE |
503 | Attachment storage service unavailable | Show retry message |
AGENT_ATTACHMENT_BUCKET_INVALID |
422 | Attachment bucket name is invalid | Show generic error and force refresh |
AGENT_ATTACHMENT_PATH_SCOPE_INVALID |
422 | Attachment path does not belong to user scope | Show generic security error and force refresh |
AGENT_SIGNED_URL_GENERATION_FAILED |
502 | Backend failed to generate attachment signed URL | Show retry toast |
AGENT_SIGNED_IMAGE_URL_INVALID |
422 | Signed image URL is invalid or expired | Show error and retry image load |
Agent Internal (Binary URL Validation)
| code | status | meaning | frontend handling |
|---|---|---|---|
INVALID_BINARY_URL_HOST |
422 | Binary URL host is not allowed | Show error and retry |
INVALID_BINARY_URL_BUCKET |
422 | Binary URL bucket name is invalid | Show error and retry |
INVALID_BINARY_URL_PATH_SCOPE |
422 | Binary URL path does not belong to allowed scope | Show error and retry |
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 |
Notification
| code | status | meaning | frontend handling |
|---|---|---|---|
NOTIFICATION_NOT_FOUND |
404 | Notification not found or not owned by current user | Show not-found message and refresh list |
Global
| code | status | meaning | frontend handling |
|---|---|---|---|
REQUEST_VALIDATION_ERROR |
422 | Request validation failed | Show invalid-request message |
INTERNAL_ERROR |
500 | Unexpected internal server error | Show generic error and allow retry |
Tool (Internal Agent Runtime)
| code | status | meaning | frontend handling |
|---|---|---|---|
MISSING_RUNTIME_ARGS |
500 | Tool call missing required runtime arguments | Show error and retry |
TOOL_REJECTED |
403 | Tool execution was rejected | Show tool rejection message |
TOOL_PENDING_APPROVAL |
202 | Tool execution awaiting approval | Show pending approval state |