qzl/eryao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a3fe85fc9a624db7fb9e25542387f2d48ee86e3
eryao/docs/protocols/common/http-error-codes.md
T
qzl 6a2a9d2c87 feat(feedback): implement user feedback collection system with email reporting 
Backend:
- Add user_feedback table with RLS policy
- Create feedback submission API (multipart/form-data)
- Implement xlsx report generation with embedded images
- Add scheduled email delivery via Feishu SMTP
- Create HTML email templates (daily_report, no_feedback)

Frontend:
- Add feedback screen with type selection and image picker
- Support anonymous submission via skipAuth flag
- Collect device info and app version

Protocol:
- Document feedback API contract and error codes
- Update http-error-codes.md with FEEDBACK_* codes
2026-04-20 12:49:54 +08:00

7.8 KiB
Raw Blame History

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

Invite

code status meaning frontend handling
INVITE_CODE_NOT_FOUND 404 Invite code not found for current user Show not-found message and trigger invite code bootstrap

Feedback

code status meaning frontend handling
FEEDBACK_CONTENT_EMPTY 400 Feedback content is empty Prompt user to enter content
FEEDBACK_CONTENT_TOO_LONG 400 Feedback content exceeds 500 characters Show character limit hint
FEEDBACK_TOO_MANY_IMAGES 400 More than 3 images uploaded Show image count limit hint
FEEDBACK_IMAGE_TOO_LARGE 400 Image file exceeds 5 MB Show image size limit hint
FEEDBACK_INVALID_IMAGE_TYPE 400 Image type not supported (only jpg/png) Show supported format hint
FEEDBACK_SUBMIT_FAILED 500 Feedback submission failed Show retry prompt

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
Reference in New Issue View Git Blame Copy Permalink