Skip to main content

Gateway calls

Mail and file clients use global fetch to the injected gateway URLs. Gateway and signed R2 origins are added by the platform, are never listed in runtime.egress.allow, and do not count against its thirteen customer origins. Mail and storage share a configured project gateway limit of approximately 1,200 calls per minute per Cloudflare location. A gateway 429 gateway_rate_limited or 503 gateway_unavailable is retryable after a delay with the same idempotency keys. Gateway 403 gateway_not_enabled and gateway_route_denied require the capability or route corrected first; they are final for the unchanged request. Gateway errors. The default mail/storage response-header timeout is 10,000 ms, configurable from 100 to 30,000 ms. deleteMany applies its configured deadline across response headers and complete control JSON; binary readMany retains its per-read idle timeout. A timeout does not undo durable progress. Runtime attachment downloads are currently unsupported. Files · Email.

API versions and interface changes

Product endpoints use the /v1 route family. The CLI, SDK and MCP are released together under one version; /v1 does not yet promise a stable interface. While the interface is young, request fields, commands and supported behavior can change without a guaranteed deprecation or sunset notice period. Pin the client release used by an automation, and review the changelog, current release and OpenAPI contract before updating. Only the current release is published; older release URLs return 404, so keep your own copy and checksum of an archive you pin. A pinned client does not freeze the server contract or guarantee that every older client remains compatible.

Request failures

Act on code, suggested_action and retryable; HTTP status only groups error codes. 401: authenticate. 402: credits, Paid access or a Stop budget block the request. 403: the account lacks permission, GitHub lacks repository access, an interactive login is required or the selected database size needs Paid. 409: a prerequisite must change, such as GitHub connection, sender domain, plan or ETag. An API 429 requires waiting for Retry-After. Repeat an unchanged request only when retryable is true; an uncertain response keeps the original request and idempotency key. Never start another payment or destructive mutation with a new key merely because its result is unknown. Database API reads and writes retain application RLS. Empty results are not proof that no rows exist, and the write count does not include every possible trigger/cascade effect. Use database access for the request and receipt contract. An oversized application result answers non-retryable SQLSTATE 54000: page reads or split writes. query(), transaction() and an autocommit held statement roll back a rejected RETURNING write or WITH statement. Inside your own BEGIN, the effects remain in that open transaction: send ROLLBACK or end the held scope without COMMIT. Input rejected before sending is database_query_invalid; an idle or expired held scope is database_unavailable and needs a new scope. A billing_issue refers to an existing invoice. Follow its address-correction or contact action and preserve that invoice; a new payment or disabled tax is not a retry strategy. Billing issues.

Waiting for work

The original operation is the source of progress. CLI --wait has a bounded local wait; the operation can continue afterward. MCP status tools return current observations. Follow the response’s polling interval and stop on terminal state. For pending mail verification, follow the returned next_check_after_seconds, currently 60 seconds. Custom-domain status returns no interval: check it again after DNS changes have had time to propagate rather than rebuilding. A Skill instruction to poll does not schedule a future agent run. Arrange your harness’s supported scheduler when authorized, or keep the operation ID and return the next command to the user. OpenAPI schemas contain the exact field, request and endpoint limits. Status · Export.