Errors

HTTP Error Response

HTTP APIs use a Google RPC Status-style JSON error body:

{
  "code": 16,
  "message": "Invalid username or password",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "UNAUTHENTICATED",
      "domain": "synctv.api",
      "metadata": {
        "errorCode": "1002",
        "errorKind": "unauthenticated",
        "requestId": "01HX..."
      }
    },
    {
      "@type": "type.googleapis.com/google.rpc.RequestInfo",
      "requestId": "01HX..."
    }
  ]
}

Field	Meaning
code	Numeric gRPC status code. The HTTP status still comes from the HTTP status line.
message	User-facing summary. 5xx details are sanitized.
details[]	Structured error details, usually including google.rpc.ErrorInfo with reason, domain, and metadata.
details[].metadata.errorCode	Application error code for programmatic handling.
details[].metadata.requestId / google.rpc.RequestInfo.requestId	Request identifier for log correlation.

429 may include a Retry-After header.

HTTP Status Codes

Status	Meaning	Client action
400	Invalid request structure, field, or format	Fix input; do not retry the same request
401	Not logged in, token expired, ticket expired, Provider credential expired	Refresh token, sign in, or rebind Provider
403	Authenticated but not allowed, email unverified, banned	Show permission reason
404	Resource, room, media, or Provider instance missing	Refresh local state
409	Already exists, concurrent update, state conflict	Read current state before retrying
408	Backend timeout	Retry with backoff
429	Rate limit or resource exhausted	Respect Retry-After
502	Upstream Provider or proxy error	Check Provider, upstream, and headers
503	Dependency or service unavailable	Retry later; operators check dependencies
504	Upstream timeout	Retry with backoff and inspect upstream

Application Error Codes

Range	Code	Meaning
Common	0	Unspecified
Auth	1000	Unauthenticated
Auth	1001	Token expired
Auth	1002	Invalid credentials
Resource	2000	Not found
Resource	2001	Already exists
Resource	2002	Resource exhausted or rate limited
Resource	2003	Conflict
Validation	3000	Invalid argument
Validation	3001	Invalid format
Validation	3002	Value too short
Validation	3003	Value too long
Validation	3004	Required field missing
Permission	4000	Permission denied
Permission	4001	Forbidden
Permission	4002	Banned
Server	9000	Internal error
Server	9001	Database error
Server	9002	Service unavailable
Server	9003	Timeout

Clients should not parse the message text for stable branching.

gRPC Errors

gRPC errors use the standard status code, message, and embedded google.rpc.Status binary details. HTTP-style x-synctv-error-code metadata is not sent as a separate trailer; clients should read google.rpc.ErrorInfo.metadata.errorCode and RetryInfo.

gRPC code	HTTP equivalent	Meaning
InvalidArgument	400	Invalid input
Unauthenticated	401	Missing or invalid auth
PermissionDenied	403	Authenticated but not allowed
NotFound	404	Resource missing
AlreadyExists	409	Resource already exists
ResourceExhausted	429	Rate limited or capacity exhausted
Unavailable	503	Service or dependency unavailable
DeadlineExceeded	504	Timeout
Internal	500	Internal server error

See gRPC Debugging.

Realtime Errors

WebSocket business errors use protobuf messages, not HTTP JSON:

Message	Scenario
ServerMessage.error	General business error, such as permission or invalid input
ServerMessage.resourceObserveError	Invalid observe id, too many observations, or resource load failure
WebSocket close	Auth failure, expired ticket, protocol error, connection limit, shutdown

Resource observation errors do not necessarily close the connection.

Provider Errors

Symptom	Typical status	Handling
Provider credential expired	401	Re-login or rebind Provider
Upstream resource missing	404	Refresh list and remove stale media
Upstream rejected request	400 or 502	Check headers, URL, format
Upstream rate limited or 5xx	502/503/504	Back off and inspect upstream
Credential encryption missing	Sanitized 500	Configure credential encryption key

Client Rules

• Classify by status: Use HTTP or gRPC status for login, permission, retry, and refresh decisions.
• Use codes: Read application codes from google.rpc.ErrorInfo.metadata.errorCode. Do not parse English text.
• Keep request IDs: Collect requestId, time, path, and status for support.
• Protect secrets: Never log tokens, cookies, OAuth2 codes, Provider credentials, or passwords.