eryao/docs/protocols/common/http-error-codes.md

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 + 3 follow-ups)	Show run-limit message and require starting a new session
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

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

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.