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 status | Typical meaning | Next step |
|---|---|---|
| 401 | Missing, invalid, expired, or revoked API key | Verify the Bearer header and key status. |
| 403 | The actor lacks a required permission or access | Check /me, key scopes, role, and the returned message. |
| 404 | The record was not found in the accessible workspace | Get an ID from a list response and verify the workspace. |
| 409 | Conflicting state, including an expired proposal | Read the message; obtain a fresh preview if needed. |
| 422 | Invalid input or an operation-specific blocker | Correct the field or blocker before retrying. |
| 429 | A rate or quota limit was reached | Honour Retry-After when present and read the error. |
| 500 | An unexpected server error | Retain the request ID; retry reads with backoff. |
| 502 | An external service failed | Read 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.
| Bucket | Burst capacity | Sustained rate |
|---|---|---|
| REST key on Free | 30 requests | 1 request every 2 seconds |
| REST key on a paid plan | 120 requests | 2 requests/second |
| REST workspace, across its keys | 600 requests | 10 requests/second |
| MCP read tools, per workspace | 120 calls | 2 calls/second |
| MCP write tools, per workspace | 30 calls | 1 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.