Errors and API versions
Handle bounded retries, preserve idempotency, and upgrade public API contracts deliberately.
Read the response envelope
JSON responses use a shared envelope with success, code, message, and data. Successful response codes identify the operation. Failed responses contain a stable machine-readable error code; do not branch on translated message text. The reference describes the exact data contract for each endpoint.
| Status | Meaning | Client action |
|---|---|---|
400 | Invalid input or request shape | Correct the input against the operation schema. |
401 | Missing, revoked, expired, or invalid authentication | Replace the credential or complete the OAuth flow again. |
403 | Missing scope, transport permission, workspace role, or allowed source IP | Review the access grant and current workspace permissions. |
404 | The authorized resource does not exist or the capability is unavailable | Check the resource and workspace. |
409 | Conflicting idempotency input or resource state | Recover the original result or change the action. |
429 | A usage, concurrency, queue, stream, or temporary abuse ceiling was reached | Respect Retry-After and reduce request frequency. |
5xx | The server or an upstream operation could not complete the request | Retry with backoff and the same idempotency key where supported. |
Validate budgets and available credits before starting expensive work. Insufficient credit or budget responses require changing the relevant financial limit or funding the selected workspace; retrying rapidly does not create capacity.
Retry safely
Use exponential backoff with jitter and a bounded retry count. Poll active jobs less frequently when status is unchanged. Honor Retry-After before every new attempt following a 429 response.
For running or retrying a Tool, keep one UUID Idempotency-Key for one logical action. Reuse it after a timeout with the same input and workspace. Create a new identifier for a new action. Never retry an ambiguous paid request with a fresh identifier before checking its existing job or result.
Authentication failures do not consume another account's credentials or permanently ban its workspace. Repeated abusive authenticated requests can temporarily suspend the offending key. The suspension expires or can be reviewed from the access settings; changing the key does not bypass the workspace's shared limits.
Public API versions
The public REST API uses /v1 for its major contract. Additive endpoints, optional fields and corrections that preserve existing behavior stay on that version. A breaking change requires a new major route, a documented upgrade path, and an announced retirement date for the old version.
Documentation releases additionally carry a date. A dated release records the contract and guidance at that point; it does not add a date header or secretly change server behavior. The current /en/api/v1 documentation always follows the current implementation. Dated OpenAPI snapshots remain available under releases.
Clients should accept new optional response fields and new documented operations. They should still validate required fields and explicitly handle unknown status values. Server request schemas remain strict: unsupported request fields are rejected.
REST and MCP share the same business contracts. The MCP transport follows its own negotiated protocol version; changing that protocol does not rename REST /v1.