Documentation Index
Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt
Use this file to discover all available pages before exploring further.
Nusomi returns conventional HTTP status codes and a structured JSON error body.
Error envelope
{
"error": {
"code": "session_not_found",
"message": "No session with id 'ses_unknown' in this workspace.",
"param": "id",
"request_id": "req_01HZ..."
}
}
| Field | Notes |
|---|
code | Stable string identifier. Code at this level. |
message | Human-readable. Do not parse this — pivot off code. |
param | Optional. The offending field, when applicable. |
request_id | Always included. Quote it when contacting support. |
Status codes
| Status | Meaning |
|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted (async work queued) |
| 204 | No content |
| 400 | Bad request — malformed payload, validation failure |
| 401 | Authentication failure |
| 403 | Authorization / scope failure |
| 404 | Resource not found in this workspace |
| 409 | Conflict — e.g. starting a session that’s already recording |
| 422 | Unprocessable — e.g. trying to seal an empty session |
| 429 | Rate limited — see rate-limits |
| 5xx | Nusomi-side error. Safe to retry with backoff. |
Error code table
Authentication / authorization
| Code | Status | Meaning |
|---|
missing_authorization | 401 | No Authorization header. |
invalid_api_key | 401 | Key not recognized or revoked. |
insufficient_scope | 403 | Valid key, wrong scope. |
workspace_disabled | 403 | Workspace suspended. |
Resources
| Code | Status | Meaning |
|---|
session_not_found | 404 | No such session in this workspace. |
frame_not_found | 404 | No such frame. |
event_not_found | 404 | No such event. |
workflow_not_found | 404 | No such workflow registered. |
export_not_found | 404 | No such export. |
Validation
| Code | Status | Meaning |
|---|
invalid_request | 400 | Generic — see param and message. |
invalid_workflow_slug | 400 | Workflow names must match ^[a-z0-9_]{2,64}$. |
invalid_metadata | 400 | Metadata too large (>16 KB) or contains banned types. |
invalid_filter | 400 | Filter combination not supported. |
unsupported_format | 400 | Export format unrecognized. |
State
| Code | Status | Meaning |
|---|
session_already_recording | 409 | start called on a session in recording. |
session_already_stopped | 409 | stop called on a session past stopped. |
session_not_sealed | 422 | Operation requires a sealed session (e.g. export). |
session_empty | 422 | Trying to seal a session with zero frames. |
Replay / recovery
| Code | Status | Meaning |
|---|
replay_diverged | 422 | Exact replay couldn’t find a target. |
replay_budget_exceeded | 422 | Guided replay ran out of budget. |
recovery_no_anchor | 422 | No usable recovery frame for the given session. |
live_sandbox_forbidden | 403 | Key lacks replay:live scope. |
Limits
| Code | Status | Meaning |
|---|
rate_limited | 429 | Per-key or per-workspace QPS exceeded. |
quota_exceeded | 429 | Monthly capture / export quota hit. |
frame_too_large | 413 | Frame upload above 10 MB. |
payload_too_large | 413 | Request body above 1 MB. |
Server
| Code | Status | Meaning |
|---|
internal_error | 500 | Nusomi bug. Retry with backoff. |
service_unavailable | 503 | Maintenance window or downstream outage. |
gateway_timeout | 504 | Upstream took too long. Safe to retry. |
Retry guidance
- 5xx and 429 are safe to retry.
- Use exponential backoff with jitter, starting at 250 ms, capped at 30 s.
- The SDKs do this automatically — see the
maxRetries option.
- 4xx is not retryable (except 429). Fix the request.
Idempotency
POST requests on /v1/sessions, /v1/exports, and /v1/replays accept an Idempotency-Key header. Same key + same body = same response, deterministically, for 24 hours. Use this to make retries safe under network partition.