Errors and limits

This page is the reference for what the REST API sends back when something goes wrong, and for the limits that apply to every integration. Use it to decide, from the status and code alone, whether to retry, fix the request, or stop.

Error shape#

Most errors share one envelope:

{
  "statusCode": 403,
  "code": "forbidden_by_agent_allowlist",
  "error": "forbidden",
  "message": "This API key is not permitted to access the specified agent."
}

• statusCode repeats the HTTP status.
• code is the machine-readable cause, when there is one. Branch on it.
• error names the status class: bad_request (400), unauthorized (401), forbidden (403), not_found (404), conflict (409) or too_many_requests (429).
• message is written for a person. Don't parse it.

A body that fails schema validation answers 400 with "code": "FST_ERR_VALIDATION" and a message naming the invalid field.

A server error hides its cause:

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred. Please try again later."
}

Other shapes#

A few responses use a route-specific body with no statusCode or code. The specific cause is in error instead:

Read code when it is present and fall back to error.

Status codes#

A 404 for a thread is identical whether the thread doesn't exist or belongs to another organization.

403 codes#

Every 403 is terminal: retrying, or renewing the credential, won't change the answer.

See Authentication and API keys for how the first three are decided. Stream errors, which arrive inside a 200, are listed on Streaming.

Rate limits#

• The chat limit is shared by everyone who talks to the agent through your organization, including every visitor of a Web SDK widget for that agent. Contact support@runbear.io before a high-traffic launch.
• A run made with a Web SDK session pass counts against both the chat limit and the session's own limits. See Web SDK session limits for what the widget does when one is reached.
• The trace limits are counted on each API server separately, so the budget you observe can be higher than the number above. Pace yourself by the headers rather than by a fixed count.
• Routes not listed here have no request limit of their own. API-key validation can still be throttled under heavy load; that answers 429 with Retry-After like any other limit. Until a pending API fix ships, a throttled validation answers 401 api_key_invalid instead, so a sudden 401 for a key that worked moments ago is worth one delayed retry.

Rate-limit headers#

Responses from rate-limited routes carry these headers on every response, successful or not:

429 responses#

{
  "statusCode": 429,
  "code": "rate_limited",
  "error": "too_many_requests",
  "message": "Too many requests. Retry after the window resets."
}

Trace 429s carry no code; wait Retry-After seconds. Treat any other 429 the same way.

Success status codes#

Most successful calls answer 200. These differ:

Pagination#

Cursors are opaque. Pass back exactly what you received, and stop when it is null. On threads and credits, a cursor the API didn't issue is refused with 400.

CORS#

The API can be called from a browser on any origin:

• Access-Control-Allow-Origin: *, without credentials. Authenticate with the Authorization header, never cookies.
• Allowed request headers: content-type, authorization, connection, cache-control and x-requested-with.
• Readable response headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After and x-runbear-thread-id (the last is still rolling out; see Chat).
• Methods: GET, POST, PUT, DELETE, PATCH, HEAD and OPTIONS.

Calling the API from a browser with an API key exposes the key. Use Web SDK session passes for browser traffic.

Related#

• Authentication and API keys
• Streaming — errors inside a stream
• Web SDK errors
• REST API overview