Errors and rate limits

REST errors use an HTTP status and JSON envelope:

{
  "error": {
    "code": "forbidden",
    "message": "Grant or account role does not permit this operation"
  }
}

Inspect error.code, not exact display wording. Additional metadata appears when relevant, such as limit and billing on quota errors.

HTTP status	Common code	Action
400	invalid_arguments, invalid_json	Correct types, supported fields, query/body envelope or JSON
401	unauthorized	Verify manual bearer, expiry/revocation and account membership
403	forbidden, invalid_origin	Check effective scope/role, dashboard boundary or request origin
404	not_found, unknown_operation	Use a supported path and owned response ID
409	idempotency_conflict	Same key had different creation arguments; reconcile intent
409	quota_exceeded	Operation did not complete; inspect limit and billing guidance
413	request_too_large	Body exceeds 256 KiB
422	validation_failed, invalid_kind	Correct model constraints or use an appropriate check kind
429	rate_limited	Wait for Retry-After
500	invalid_result	Server could not produce the required output; retain request context for support

Errors deliberately avoid echoing potentially sensitive input/model messages. validation_failed can identify fields without returning their submitted values. Do not infer cross-account resource existence from a not-found response.

Automation limits

Requests are counted in minute windows:

Boundary	Limit
Client IP	120 requests/minute
Grant	60 requests/minute
Account	300 requests/minute

The same authentication layer serves REST and MCP. An exceeded boundary returns Retry-After: 60. Request bodies are limited to 256 KiB. Use bounded pagination rather than oversized requests.

HTTPS is required outside local development. If an Origin header is sent, it must match the app origin; this is not a general cross-origin browser API.

Use backoff for rate limits and transient transport failures. Retry creates with the same idempotency key for the same intended operation. Do not blindly retry invalid configuration, permission failures or a quota error.

For quotas, show the returned limit and available billing upgrade URL. A null URL means self-service purchasing is unavailable; lack of billing permission requires a billing-authorized account member.