Skip to main content
Every error response carries a JSON body with a .error field:

​
HTTP status codes

What it means: the server understood the route but your request body or path params were invalid.Common causes:
  • Missing task or endUserId on POST /v1/tasks
  • Blank task string (empty or whitespace-only)
  • endUserId longer than 256 characters
  • Malformed JSON body
  • Invalid fields list on DELETE credentials
What to do: read the error message, fix your request, retry.
What it means: no Authorization header, or the token isn’t the right type for the endpoint.Common causes:
  • Header omitted entirely
  • Expired Cognito JWT — re-authenticate via the dashboard
What to do: mint a fresh token / API key and retry.
What it means: the token was recognized but denied.Common causes:
  • API key has been revoked
  • Attempting to read/write resources belonging to another business
  • Attempting to submit a follow-up into a sessionId that isn’t yours
What to do: revoked keys aren’t recoverable — mint a new one. Cross-tenant denial is intentional; there’s no way around it.
What it means: the resource doesn’t exist, or it does but you don’t own it (we deliberately don’t distinguish the two).Common causes:
  • Unknown taskId on GET /v1/tasks/{taskId}
  • Unknown sessionId on GET /v1/sessions/{sessionId}
  • API-key prefix that was never issued, or belongs to another business
What to do: double-check the ID and confirm it belongs to the caller’s business.
What it means: wrong HTTP verb for the endpoint.What to do: check the endpoint doc for the allowed verbs.
What it means: the business has hit its monthly task quota (15 on the free tier, higher if you’ve arranged it).The response body tells you how many you’ve used and the current cap:
What to do:
  • Wait until the start of next month — the counter resets automatically.
  • Or email team@stablebrowse.ai to have your limit raised.
See Authentication → Rate limits for details.
What it means: our bug.What to do: retry with exponential backoff (we often recover within seconds). If it persists, report to team@stablebrowse.ai with the timestamp and (ideally) the request ID from response headers.

​
Task-level errors

A task that reaches status: "failed" carries an error string explaining what went wrong. This is distinct from the HTTP error codes above — the API call itself succeeded (GET /v1/tasks/{id} returns 200), but the underlying agent run didn’t produce a useful answer. Common patterns:

​
SDK exceptions

The Python and TypeScript SDKs map HTTP errors into a typed exception hierarchy. See Python SDK → Exceptions and TypeScript SDK → Exceptions.
All three exceptions derive from StablebrowseError. TaskFailed and TaskTimeout both carry the underlying task on .task for inspection.

​
Retry guidance

For tasks.run specifically, the SDKs’ built-in polling handles transient 5xx on GET /v1/tasks/{id}. You don’t need to implement retries for the polling loop itself.