Errors

Errors and troubleshooting

Read the local error envelope, map status codes to recovery actions and debug without leaking secrets.

Updated 29 July 2026Local API · v1 contract

On this page

Error envelope Common status codes Recovery sequence Safe diagnostics

Error envelope

JSON

{
  "error": {
    "code": "INVALID_GUI_SESSION",
    "message": "The GUI session is invalid or expired.",
    "recoverable": true,
    "errorId": "OSS-1A2B3C4D"
  }
}

OpenSS uses a stable machine-readable code, a user-facing message and a recoverable flag. Unexpected server failures may include errorId; pass that identifier to a maintainer instead of sharing logs containing request data.

Common status codes

Status	Codes	What to do
400	INVALID_LAUNCH_TOKEN, SCREENSHOT_REQUIRED, INVALID_SCREENSHOT_ID	Correct the lifecycle or request fields; do not blindly retry the same expired ID.
401	INVALID_GUI_SESSION, ACCOUNT_SIGN_IN_REQUIRED	Exchange a fresh local launch token or refresh the account-backed session.
403	INVALID_ORIGIN, BYOK_REQUIRES_PRO, CHAT_CONTEXT_REQUIRES_PRO	Use the approved local origin or the required entitlement; changing the local header alone cannot grant access.
404	INVALID_SCREENSHOT_ID, CHAT_CONTEXT_NOT_FOUND	Capture or address the resource again.
409	HISTORY_DISABLED	Enable a history backend before creating a persistent chat.
413	REQUEST_TOO_LARGE, INPUT_TOO_LARGE, SCREENSHOT_TOO_LARGE	Reduce the request or image size.
422	INVALID_REQUEST	Fix JSON field types, enum values or required fields.
503	HOSTED_AI_UNAVAILABLE	Retry with backoff after checking account/network availability.

Recovery sequence

01
Identify the boundary
Check whether the failure is local session, account entitlement, capture, provider or upstream hosted AI.
02
Check the version
Call /api/version. A missing response indicates a process, port or local origin issue rather than a chat payload issue.
03
Refresh only what expired
Exchange a new launch token for a local session. Refresh account authentication separately when hosted AI returns account errors.
04
Retry deliberately
Retry transient 503 responses with bounded backoff. Do not retry invalid tokens, expired screenshot IDs or malformed bodies unchanged.
05
Clean up
Delete any screenshot ID you created, including after an error.

Safe diagnostics

Shell

curl -sS "$BASE_URL/api/version"
curl -sS "$BASE_URL/api/health" \
  -H "X-OpenSS-Session: $SESSION_TOKEN"

# Safe report fields:
# - OpenSS surface and version
# - HTTP status and error.code
# - errorId, if present
# - reproducible request shape with secrets removed

Contract source: OpenSS/src/openss/gui/server.py and schemas.py.