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

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