Error codes and recovery
Choose a recovery action using the structured error code rather than HTTP status alone.
HTTP failures return error.code, message, retryable, and requestId. Responses also include X-Request-Id; retryable rate/capacity failures include Retry-After.
| Code | Meaning | Recovery |
|---|---|---|
| UNAUTHENTICATED | Missing, invalid, or revoked project credential | Correct backend configuration |
| VALIDATION_ERROR / INVALID_JSON / INVALID_REQUEST | Unsupported or malformed input | Correct the request; do not retry unchanged |
| INSUFFICIENT_CREDITS | Not enough unreserved credits for the requested lifetime | Fund the account or release reservations |
| BILLING_FROZEN | New use is blocked by billing state | Resolve with the instance operator |
| TENANT_CONCURRENCY_LIMIT | Shared account allowance is occupied | Release owned browsers or reduce concurrency |
| CREATE_RATE_LIMITED | Too many creation requests | Honor Retry-After; bounded capacity waiting can handle this |
| NO_CAPACITY / STARTUP_BUSY | No allocatable browser or startup slot | Retry within a bounded deadline if appropriate |
| IDEMPOTENCY_CONFLICT | Same key used with different parameters | Recover the original request; use a new key only for new work |
| SESSION_NOT_READY | Operation requires a ready browser | Wait for readiness and recheck state |
| SESSION_ENDED | Browser session ended or expired | Treat the old browser as ended; create a new workflow if needed |
| CONTROLLER_UNAVAILABLE | Automation cannot control the browser now | Inspect handoff/controller state |
| HANDOFF_UNAVAILABLE / HANDOFF_NOT_ACTIVE | Handoff state does not allow the request | Refresh state and follow the handoff lifecycle |
| SESSION_FILES_UNAVAILABLE | Files cannot be accessed in this session state | Retrieve files while ready, before closure |
| FILE_TOO_LARGE / FILE_QUOTA_EXCEEDED | File or session storage limit reached | Reduce size or remove unneeded ready files |
| FEATURE_NOT_ENABLED | Requested optional capability is unavailable | Check the availability matrix |
SDK errors
APIError contains a server failure. RequestTimeoutError and WaitTimeoutError describe local deadlines; they do not prove a remote operation was canceled.
ResultUnknownError means acceptance is uncertain and needs idempotent recovery or inspection. CleanupError means owned resource cleanup was not confirmed; preserve its recovery information.
Python's base exception is SDKError; TypeScript's is TabSailError. See the SDK references for the complete exported error classes.