Requests and errors

Use JSON over HTTPS. Mutations require Idempotency-Key; create a new key for a new intent and reuse it only when retrying the same request. Resource responses use {data, request_id}. Lists use {items, next_cursor, request_id}. Preserve unknown additive response fields.

Pagination

List requests accept limit (default 50, maximum 100) and an opaque cursor. Pass next_cursor unchanged until it is null. Cursors remain bound to authorization context; they cannot be used to browse another tenant or environment.

Idempotency

The key is scoped to tenant, environment, actor, method, and path. The same canonical body resolves to the same resource; changed input returns 409. Full replay lasts seven days. Metadata tombstones last 90 days, prevent recreation, and may return 410 after replay expiry. Secret responses are never replayed in raw form.

Do not blindly retry a write after a timeout. For an admitted run, recover its identity through the same key. For an external tool write, reconcile its stable operation ID. An explicit replacement run uses a new key and retry_of_run_id; unresolved writes prevent that retry.

Errors

{"error":{"code":"quota_exceeded","message":"Environment budget exhausted.","retryable":false},"request_id":"req_example"}

HTTP	Meaning	Client action
400	Invalid request	Correct the input
401	Invalid/expired credentials	Refresh or replace credentials
403	Missing authority or scope	Request the right permission
404	Missing or inaccessible resource	Do not infer another tenant's resources
409	State/idempotency conflict	Resolve the conflict
410	Expired replay or resource	Inspect the retained outcome; do not recreate blindly
429	Rate, concurrency, or budget limit	Honor Retry-After when supplied
503	Admission unavailable	Retry only as allowed by idempotency and retryable

Use request_id when contacting support. Do not send keys, raw prompts, files, or authorization headers. SDK read retries are bounded to two transient retries. Mutation retries preserve the same key and payload; business conflicts are not retried.