Skip to Content

API reference / Get started

Errors and rate limits

Identify what failed, wait when needed, and retry safely.

REST errors use an error object. Validation errors may identify a field:

{
  "error": {
    "code": "VALIDATION",
    "message": "id must be a UUID.",
    "field": "id"
  }
}
HTTP statusTypical meaningNext step
401Missing, invalid, expired, or revoked API keyVerify the Bearer header and key status.
403The actor lacks a required permission or accessCheck /me, key scopes, role, and the returned message.
404The record was not found in the accessible workspaceGet an ID from a list response and verify the workspace.
409Conflicting state, including an expired proposalRead the message; obtain a fresh preview if needed.
422Invalid input or an operation-specific blockerCorrect the field or blocker before retrying.
429A rate or quota limit was reachedHonour Retry-After when present and read the error.
500An unexpected server errorRetain the request ID; retry reads with backoff.
502An external service failedRead the message; retry reads with backoff.

The message can contain a more specific reason than the status. In particular, a blocked operation is not always an authentication problem.

Request rate limits

Limits use token buckets: a short burst is allowed, then capacity refills at the sustained rate. These are the current configured limits for non-internal workspaces, separate from plan and usage allowances.

BucketBurst capacitySustained rate
REST key on Free30 requests1 request every 2 seconds
REST key on a paid plan120 requests2 requests/second
REST workspace, across its keys600 requests10 requests/second
MCP read tools, per workspace120 calls2 calls/second
MCP write tools, per workspace30 calls1 call every 2 seconds

Both the key and workspace limits apply to REST requests. Wait for the supplied retry time; add backoff and jitter rather than retrying in parallel. MCP tool-level failures appear as isError: true, which must be checked even when the HTTP response succeeded.

Writes and retries

There is no documented general-purpose idempotency header for ordinary writes. After a timeout, check the resource state before repeating a create or update.

For supported preview/confirm operations, keep the proposal ID and retry confirmation using that same ID rather than creating another purchase. An already-executed proposal returns its recorded state; if execution has been claimed but no result is available yet, check again before concluding it completed. Proposals that have not been executed expire after 15 minutes.

Include the response’s x-request-id, when available, in a support report. Never send your authorization header.

On this page