How many requests you can make, what happens when you go over, and how errors are shaped.

Rate limits

Endpoints	Limit
`/v1/*` (chat completions, agent completions, knowledge search, models)	300 requests per minute per workspace
All other endpoints	120 requests per minute per key

Some endpoints have their own lower limit on top of this, for example the analytics endpoints.

When you go over a limit you get 429 Too Many Requests with a Retry-After header that says how many seconds to wait:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "This API key made too many requests (limit 120/minute). Try again in 27 seconds.",
    "detail": { "code": "API_KEY_RATE_LIMITED" }
  }
}

Wait for the number of seconds in Retry-After, then retry. Do not retry in a tight loop.

Error format

Errors are JSON with one envelope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "A sentence you can show to a person.",
    "detail": { "code": "API_KEY_SCOPE_MISSING" }
  }
}

error.code is the general class of the error.
error.message explains what happened in plain language.
error.detail.code, when present, is a stable code your client can branch on.

Status codes

Status	Meaning	What to do
`400`	The request is not valid for this endpoint.	Fix the request; the message says what is wrong.
`401`	The key is missing, invalid, expired or revoked.	Check the key; create a new one if it expired.
`402`	The workspace balance is empty or a spending limit is reached.	Top up the balance or raise the limit in the app.
`403`	The key or the person behind it is not allowed to do this.	See the codes below.
`404`	The resource does not exist or is not visible to this key.	Check the id and whether the resource is shared with the key's owner.
`422`	A field has the wrong type or is missing.	Fix the body; the message names the field.
`429`	Too many requests.	Wait for `Retry-After` seconds.
`5xx`	Something went wrong on our side.	Retry with backoff.

Status	`error.detail.code`	Meaning
`403`	`API_KEY_SCOPE_MISSING`	The key lacks the scope this endpoint needs. The message names it.
`403`	`API_KEY_SCOPE_UNMAPPED`	This endpoint is not available to API keys.
`403`	`API_KEY_HITL_DECIDE_FORBIDDEN`	Approvals are decided by a person in the app.
`403`	`API_KEY_POLICY_CHANGE_FORBIDDEN`	Approval, confirmation and privacy settings are changed in the app.
`429`	`API_KEY_RATE_LIMITED`	This key made too many requests.

Rate limits and errors

Rate limits

Error format

Status codes

Key-related codes