Platform

Limits and Errors

View as Markdown

Rate limits, concurrency caps, and error reference.

Session limits

LimitValue
Max concurrent sessions per workspace10
Max TTL3600 seconds (1 hour)
Default TTL1800 seconds (30 minutes)
Min TTL60 seconds
Max session creations per minute20

Rate limits

EndpointLimit
POST /v1/sessions20 per minute per workspace
POST /v1/sessions/:id/screenshot60 per minute per session
POST /v1/sessions/:id/preview-token10 per minute per session

Rate limit responses include a Retry-After header with the number of seconds to wait.

Error format

All errors follow a consistent shape:

1{
2  "error": {
3    "code": "error_code",
4    "message": "Human-readable description."
5  }
6}

Error reference

Session errors

StatusCodeMessageMeaning
404session_not_foundSession not found.The session doesn’t exist or belongs to a different workspace.
409session_not_openSession is already in a terminal state.The session is closed or expired. Already stopped — safe to ignore on cleanup.
409session_not_readySession is not ready yet.Still provisioning. Wait and retry.

Rate limit errors

StatusCodeMessageMeaning
429rate_limitedToo many requests.You’ve hit a rate limit. Check Retry-After header.
429concurrency_limitConcurrency limit reached.Too many active sessions. Delete some before creating more.

Billing errors

StatusCodeMessageMeaning
402payment_requiredInsufficient balance.Workspace balance is zero. Top up to create new sessions.

Authentication errors

StatusCodeMessageMeaning
401unauthorizedMissing or invalid API key.Check the Authorization: Bearer header.
403forbiddenAccess denied.The key is valid but doesn’t have access to the requested resource.

Input errors

StatusCodeMessageMeaning
400invalid_requestRequest body is malformed.Check the request body against the API reference.
400invalid_fieldInvalid value for field: field_name.A field value is out of range or wrong type.

Retry guidance

  • 429 rate_limited — wait the number of seconds in Retry-After, then retry.
  • 409 session_not_ready — wait 2 seconds and poll again.
  • 500 or 503 — transient server error. Retry with exponential backoff.
  • 409 session_not_open — the session is already dead. No retry needed.