Error codes

Every error response has the shape:

json
{ "error": { "code": "SW_*", "message": "..." } }

code is stable across releases. message is human-readable and may be localised. Match on code in code.

Auth (`SW_AUTH_*`)#

Code	HTTP	Meaning
`SW_AUTH_INVALID_TOKEN`	401	Token failed validation.
`SW_AUTH_EXPIRED_TOKEN`	401	Token expired. Refresh.
`SW_AUTH_OIDC_FAILED`	400	OIDC code exchange failed.
`SW_AUTH_REDIRECT_MISMATCH`	400	`redirect_uri` doesn't match config.
`SW_AUTH_INSUFFICIENT_PERMISSION`	403	You lack the required permission/role.
`SW_AUTH_TENANT_MISMATCH`	403	Token's `tenant_id` doesn't match the resource.

Code	HTTP	Meaning
`SW_TENANT_NOT_FOUND`	404	Tenant id doesn't exist.
`SW_TENANT_CAPACITY`	409	One of the tenant's limits hit.
`SW_NOT_MEMBER`	403	Caller is not a member of the resource.

Code	HTTP	Meaning
`SW_ROOM_NOT_FOUND`	404
`SW_ROOM_FORBIDDEN`	403
`SW_ROOM_FROZEN`	409	Closed or archived.
`SW_ROOM_TYPE_INVARIANT`	400	Op invalid for this `room_type`.
`SW_ROOM_CAPACITY`	409	Tenant max_participants reached.
`SW_ROOM_EXPORT_REFUSED`	400	Sidekick/bridge/incognito/federated.
`SW_ROOM_IMPORT_REFUSED`	400	Same.

Code	HTTP	Meaning
`SW_NOTE_NOT_FOUND`	404
`SW_NOTE_FORBIDDEN`	403
`SW_NOTE_CONFLICT`	409	Concurrent edit; resolve via CRDT path.
`SW_NOTE_QUOTA_EXCEEDED`	409

Code	HTTP	Meaning
`SW_AI_NO_TOKEN`	503	No ScaiGrid token available.
`SW_AI_MODEL_NOT_FOUND`	404	Model not registered with this tenant.
`SW_AI_BUSY`	409	Already generating.
`SW_AI_BUDGET_EXCEEDED`	429	Monthly token cap hit.
`SW_PLUGIN_FORBIDDEN`	403	Plugin disabled for tenant/room.
`SW_PLUGIN_NOT_FOUND`	404
`SW_PLUGIN_TIMEOUT`	504	Tool call exceeded 30s.

Code	HTTP	Meaning
`SW_PLAN_NOT_FOUND`	404
`SW_PLAN_NOT_RUNNING`	400	Op requires running.
`SW_PLAN_NOT_PAUSABLE`	400
`SW_PLAN_NOT_RUNNABLE`	400
`SW_PLAN_TOO_MANY_STEPS`	400	> 20 steps.
`SW_PLAN_EMPTY_STEPS`	400
`SW_PLAN_EMPTY_GOAL`	400
`SW_PLAN_UNKNOWN_STEP`	400
`SW_PLAN_STEP_TERMINAL`	400	Step already done/failed/skipped.
`SW_PLAN_BAD_MODE`	400
`SW_PLAN_BAD_ADVANCE`	400
`SW_PLAN_BAD_NEXT_ACTION`	400
`SW_PLAN_NEEDS_SIDEKICK_ROOM`	400	`venue=sidekick` without room id.
`SW_PLAN_BAD_VENUE`	400

Code	HTTP	Meaning
`SW_SIDEKICK_NOT_FOUND`	404
`SW_SIDEKICK_CAP_REACHED`	429	Per-user / per-tenant concurrency hit.
`SW_SIDEKICK_TIMEOUT`	504	Task exceeded its wall-clock cap.

Code	HTTP	Meaning
`SW_FED_PEER_UNKNOWN`	403	Sender server not in `allowed_peers`.
`SW_FED_SIGNATURE_MISMATCH`	401	Event signature failed verification.
`SW_FED_PROTOCOL_VERSION`	400	Unsupported protocol version.
`SW_FED_REFUSED`	403	Room or tenant has federation disabled.

Code	HTTP	Meaning
`SW_BRIDGE_NOT_FOUND`	404
`SW_BRIDGE_SIGNATURE_MISMATCH`	401	Inbound HMAC failed.
`SW_BRIDGE_PAUSED`	409	Bridge is paused.
`SW_BRIDGE_TRANSPORT_ERROR`	502	Foreign system unreachable.

Code	HTTP	Meaning
`SW_NOT_FOUND`	404	Generic.
`SW_VALIDATION_ERROR`	422	Pydantic schema validation failed (details in `error.details`).
`SW_INTERNAL_ERROR`	500	Bug. Includes a `request_id` to grep server logs.
`SW_SERVICE_UNAVAILABLE`	503	Downstream (DB / Redis / NATS) unreachable.