Errors

The API uses ordinary HTTP status codes. A 2xx means success. Anything else comes with a JSON body that says what went wrong.

The error shape

Every error body has the same shape:

{
  "statusCode": 403,
  "error": "insufficient_scope",
  "message": "This API key needs the experts:write scope.",
  "requiredScopes": ["experts:write"],
  "missingScopes": ["experts:write"],
  "requestId": "req_01M726GS84892WE68HMF286YFH"
}

Some errors add fields of their own: requiredScopes and missingScopes on insufficient_scope, and retryAfterSeconds on rate_limited.

Branch on statusCode first, then on error.

Request ids

Every response, success or error, carries an X-Request-Id header such as req_01M726GS2P1N4DCP7FARE8MA4F. Quote it when you contact support. It also finds the request in Developers → Request log.

You can send your own X-Request-Id (up to 64 letters, digits, ., _, : or -). The API keeps it and returns it, so you can match API requests to your own logs. Anything else is replaced with a new id.

Server errors

An unexpected failure answers 500 with a generic message and an errorId, which is the same value as requestId:

{
  "statusCode": 500,
  "message": "Something went wrong. Please try again.",
  "errorId": "req_01M726GS2P1N4DCP7FARE8MA4F",
  "requestId": "req_01M726GS2P1N4DCP7FARE8MA4F"
}

The details stay in Rydhm’s logs under that id.

Status codes

Errors during a stream

A chat reply stream (GET /v1/chat/conversations/{id}/stream) sends its headers before the reply is generated. If the reply fails after that, the stream carries an error frame instead of an HTTP status:

data: {"type":"error","message":"Something went wrong. Please try again."}

Rate limits

Rate limits stop runaway loops and abuse. They are set well above normal use.

Each limited route counts requests in fixed windows, in two buckets at once:

• the workspace, shared by everyone and every key in it;
• the key, so one integration can’t use up the whole workspace’s budget.

A request is refused when either bucket is full.

Headers

Rate-limited routes return the state of the tightest budget the request touched:

HTTP/1.1 201 Created
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 233
X-RateLimit-Reset: 21

Routes without a limit, such as reading an expert, don’t send these headers.

When you hit a limit

The API answers 429:

{
  "statusCode": 429,
  "error": "rate_limited",
  "message": "Too many chat requests. Try again in 12 seconds.",
  "retryAfterSeconds": 12,
  "requestId": "req_01M726GS2P1N4DCP7FARE8MA4F"
}

Wait Retry-After seconds, then retry. Don’t retry in a tight loop: every retry inside the window is refused too. The SDKs retry 429 responses for you with backoff.

Limits by route

The MCP endpoint also lets one key run at most 3 ask_… questions at the same time. See MCP.

Voice sessions are also capped by how many calls a workspace may run at once. Past the cap, a new session gets 429 with error: "concurrency_limit".

Public routes

The public routes under /v1/public/… need no key. They are limited per visitor IP address and per expert instead. A refused request gets 429 with a Retry-After header and the message “Too many requests. Please wait a moment and try again.” These routes don’t send the X-RateLimit-* headers.