Skip to main content

​
Rate limits

Every tool is rate limited per workspace: The budget is shared by everyone and every agent working in the workspace, and some tools spend more than one unit per call, so parallel sessions can trip a window sooner than these numbers suggest. When a read is refused for rate, some tools still answer with the affected fields null and a retryable gap rather than an error. A rate_limit_exceeded error carries a Retry-After header naming the window you tripped. Wait that long. Do not guess a backoff. get_workspace_overview makes three internal reads per call and spends three units of a shared internal budget, so at most about 20 overviews fit in a minute. Call it once at the start of a session, not before every question.

​
Page sizes and caps

Each reference page states its tool’s limits. The common shapes:
  • Cursor paging. Tools with cursor return metadata.pagination with has_more and next_cursor. Pass next_cursor back with the same other arguments. Cursors expire after 15 minutes.
  • Bounded results. Tools without a cursor cap their rows and say so with a scope_truncated gap whose what_to_do names the parameters that narrow the query. Narrow the query; retrying the same call returns the same result.
  • Batch inputs. Tools that take people take at most 500 per call. Larger lists go in chunks against one preview (action: "append" with the same token).

​
Latency

Most reads answer in 1 to 5 seconds. Program-wide reads take longer: get_program_report and get_invite_recommendations can take 7 to 9 seconds, and the first call of a session about 5.

​
Error codes

A failed call returns status: "error", data: null and an error object with the same fields as a gap: code, message, what_failed, what_to_check, what_to_do, retryable. A failed read is always an error, never an empty result.

​
When to retry

  • Reads: retry once on internal_error or any error with retryable: true. Never retry a non-retryable gap: the answer will not change.
  • Writes: retry only with the same client_request_id. A write that already went through replays its first answer and is never repeated. A new id is a new write.
  • Sends: never resend a Luma invite or a partner invitation to “check”. Read the send’s status instead (activate_list action: "status", manage_collab_partners action: "status").