Error Codes

This page describes the stable SDK Open business error codes used by Command WebSocket responses, Command/Video events, and business method status results.

Integrations should branch on code first. message is intended for logs and diagnostics, and should not be the only decision key.

Response Shape

Command WebSocket responses use this common shape:

{
  "request_id": "req-001",
  "id": "req-001",
  "code": 0,
  "message": "ok",
  "data": {},
  "ts": 1710000000
}

Field	Description
request_id	Matches the request request_id.
id	Compatibility field. It currently matches request_id.
code	Stable status code. 0 means success.
message	Short status message for logs and diagnostics.
data	Response data or extended error details.
ts	Server Unix timestamp in seconds.

Event Shape

Command/Video events use this common shape:

{
  "event": "capture.completed",
  "code": 0,
  "message": "ok",
  "payload": {},
  "ts": 1710000000
}

Field	Description
event	Event name.
code	Event status code. 0 means success.
message	Short status message for logs and diagnostics.
payload	Event business payload.
ts	Server Unix timestamp in seconds.

Error Code Groups

Range	Category	Description
0	Success	Request or event completed successfully.
1000-1099	Request protocol errors	Request shape, method name, parameters, or rate limiting.
1100-1199	Auth and authorization errors	Token, session, capability, device scope, or auth scene errors.
1200-1299	Device errors	Device discovery, open, busy, model support, or disconnect errors.
1300-1399	Video and capture errors	Stream, preview resolution, capture failure, or capture timeout errors.
1700-1799	SANE errors	SANE runtime, device, option, scan, or profile errors.
1900-1999	Runtime and provider errors	SDK runtime internal errors or provider wiring/call errors.

SDK Open Status Codes

code	Name	Description	Suggested action
0	OK	Success.	Read data.
1000	INVALID_REQUEST	Request is not a valid JSON object.	Check Command WS envelope.
1001	INVALID_METHOD	method is missing or invalid.	Use a public method name.
1002	INVALID_PARAMS	Parameter missing or invalid.	Fill parameters according to the reference.
1003	UNSUPPORTED_METHOD	Method or format is unsupported.	Call system.capabilities to confirm capability.
1004	RATE_LIMITED	Rate limit hit.	Reduce request rate.
1100	AUTH_REQUIRED	Current connection has no session.	Call auth.create_session first.
1101	TOKEN_INVALID	API key invalid.	Check key value, status, and license mode.
1102	TOKEN_EXPIRED	API key or token expired.	Rotate or reissue the key.
1103	SESSION_TOKEN_INVALID	Session token invalid.	Create a new session.
1104	ACCOUNT_TYPE_NOT_ALLOWED	Account tier not allowed.	Upgrade key tier or check capability.
1105	DEVICE_NOT_IN_AUTH_SCOPE	Device is outside auth scope.	Update API key deviceScope.
1106	AUTH_SCENE_MISMATCH	The current auth scene does not satisfy SDK requirements.	Check auth scene configuration and reissue authorization.
1107	CAPABILITY_NOT_ALLOWED	The current session lacks method permission, or the requested parameter-level feature exceeds the current entitlement tier. For example, a VIP/SVIP/SVIP+ feature is not authorized, or an online API key is not commercially authorized and the requested feature exceeds the purchased tier.	Check auth_context.capabilities, auth_context.account_type, auth_context.licensed_account_type, and the entitlement tier required by the method parameters. Upgrade the key tier or complete commercial authorization before retrying.
1108	OFFLINE_AUTH_CODE_INVALID	Offline activation code invalid.	Generate a code for the current machine code.
1109	ONLINE_AUTH_UNAVAILABLE	Online auth unavailable.	Check gateway URL and network.
1110	USAGE_LIMIT_EXCEEDED	Quota exceeded. This also applies when a trial session calls a VIP/SVIP/SVIP+ restricted feature after the shared trial quota has been exhausted, for example with message trial quota exhausted.	Wait for quota reset, upgrade tier, complete offline activation, or complete online commercial authorization. Do not keep retrying the same restricted feature after trial quota is exhausted.
1111	OFFLINE_BINDING_MISMATCH	Offline authorization does not match machine.	Generate a new code for the current machine.
1200	DEVICE_NOT_FOUND	Device not found.	Check connection and device ID.
1201	DEVICE_BUSY	Device busy.	Stop video or close device before retrying.
1202	DEVICE_OPEN_FAILED	Failed to open device.	Check driver, permissions, and provider.
1203	DEVICE_NOT_OPEN	Device not open.	Call device.open first.
1204	DEVICE_MODEL_UNSUPPORTED	Device model unsupported.	Check device capabilities.
1205	DEVICE_DISCONNECTED	Device disconnected.	Reconnect the device.
1300	STREAM_NOT_FOUND / STREAM_NOT_READY	Stream not found or not ready. Both names currently share the same numeric value.	Call video.start again and wait until the stream is ready.
1301	CAPTURE_FAILED	Capture failed.	Check device state and profile.
1302	PREVIEW_RESOLUTION_UNSUPPORTED	Preview resolution unsupported.	Use a resolution returned by device.get.
1303	CAPTURE_TIMEOUT	Capture timeout.	Increase timeout_ms or check device.
1700	SANE_NOT_AVAILABLE	SANE unavailable.	Linux only; check provider and SANE runtime.
1701	SANE_DEVICE_NOT_FOUND	SANE device not found.	Refresh with sane.list.
1702	SANE_DEVICE_BUSY	SANE device busy.	Close old sessions and retry.
1703	SANE_OPTION_INVALID	SANE option invalid.	Set values according to sane.get_options constraints.
1704	SANE_SCAN_FAILED	SANE scan failed.	Check device, paper, and driver logs.
1705	SANE_PROFILE_NOT_FOUND	Profile not found.	Refresh profile list.
1900	INTERNAL_ERROR	Internal error.	Check runtime logs.
1901	PROVIDER_NOT_READY	Provider not ready.	Check runtime startup and provider wiring.
1902	PROVIDER_CALL_FAILED	Provider call failed.	Check provider error and logs.