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 + 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

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.