Limits and errors
Rate limits, quotas, idempotent retries, pagination, versioning and every error code.
Rate limits
Limits apply to each organization, and every credential in it draws on them: people's tokens, API keys and MCP tool calls alike.
| What | Limit |
|---|---|
Creates (POST /v1/instances) | 10 a minute |
| Every other request | 600 a minute |
| Requests without a valid credential, per source address | 60 a minute |
New connections to attest endpoints, per source address | 1 a second, bursts of 5 |
A create counts as one of the 10 once the API has accepted its headers, scopes and body and found its idempotency key unused, whatever it returns after that. A request with waitFor counts once, however long it waits. Over a limit, the API returns 429 rate_limited with Retry-After, and the request does not use up its idempotency key. Limits can change without a new API version.
Quotas
Each organization has quotas on its on-demand instances and their vCPUs, which count from create to delete, stopped instances included. GPU instances, reserved or spot, do not count. A new organization's quotas are small, and rise once it has paid its first invoice. Agent keys, and tokens issued to agents, can carry limits of their own on instances, vCPUs, sizes and locations. GET /v1/limits returns them with what is in use:
{ "agent": true, "caller": { "instances": { "limit": 2, "inUse": 1 } }, "org": { "instances": { "limit": 5, "inUse": 3 }, "vcpus": { "limit": 16, "inUse": 8 } } }An absent limit means no ceiling. A create that would exceed one returns 403 quota_exceeded, naming the limit and the largest count that fits.
Payment method
An organization adds a payment method before it starts anything billed: an owner adds a card in Settings → Billing, and usage is charged to it monthly. Until then, and while its invoices are unpaid, creating, starting or extending instances, adding a dedicated IPv4, creating clusters or node pools, growing a pool, and requesting or approving reservations return 402 payment_required. Reading, scaling down and deleting always work, and nothing that is running is stopped. Before billing opens, every organization gets 402 payment_required, and its detail says so. GET /v1/billing returns paymentRequired.
Retries and idempotency
Every POST needs an Idempotency-Key header, and every DELETE accepts one. Use a fresh UUID for each new intent and the same key for every retry of it:
- While the first request with a key is running, a retry returns
409 idempotency_in_flightwithRetry-After. - When it succeeds, the key is recorded: a retry returns the same status and the current state of what it made, with
Idempotent-Replayed: true, and creates nothing new. - When it fails, for any reason, the key is released, so you can fix the request and retry with the same key.
- The same key with a different request returns
422 idempotency_conflict. - Keys are kept for the life of what they created plus 90 days.
GET /v1/instances?idempotencyKey=<key>finds what a create made if you lost its response.
For every error with retryable: true, wait at least Retry-After seconds, retry the same request with the same key, and back off exponentially, with jitter, if the same error repeats.
Errors
Every error is an RFC 9457 problem document, application/problem+json:
{
"type": "https://api.cloud.confidential.ai/errors/invalid_request",
"title": "Invalid request",
"status": 400,
"detail": "2 problems with the request.",
"code": "invalid_request",
"retryable": false,
"requestId": "req_AGIC2LTRKTECGEAEYZOHXRS6CP",
"params": [
{ "pointer": "/size", "code": "invalid_value", "message": "…", "allowedValues": ["c1.2x", "c1.4x", "s1.2x", "s1.4x", "m1.2x"] },
{ "pointer": "/disks", "code": "required", "message": "The image needs the disk user-data." }
],
"details": {}
}- Branch on
code. Its status never changes, and the set of codes is open: for one you do not know, fall back onstatusandretryable. paramslists every problem with the request at once, each at a JSON Pointer into the body or a parameter name, withallowedValueswhen the accepted values are a known set.detailscarries the numbers you need to recover, documented with each code.- Quote
requestId(also in theX-Request-IDheader) when you contact us.
400 or 422. 400 invalid_request means the request needs fixing: something is missing, malformed or unknown. 422 unsupported_combination means each value is valid but they do not go together, such as a size the image does not run on; change one of the fields it names. A request with both kinds of problem gets 400, with every violation listed.
| Code | Status | Retry | Meaning |
|---|---|---|---|
invalid_request | 400 | no | The request is malformed or a value is invalid. params lists every violation. |
api_version_required | 400 | no | The Api-Version header is missing. |
unsupported_api_version | 400 | no | The API does not serve that version; details.supportedVersions lists those it does. |
idempotency_key_required | 400 | no | A POST was sent without Idempotency-Key. |
unauthenticated | 401 | no | The credential is missing, malformed, unknown or revoked, or the token expired. |
key_expired | 401 | no | The API key expired. |
payment_required | 402 | no | Your organization has no payment method, or its invoices are unpaid, or billing has not opened yet; an owner adds one in Settings → Billing. |
insufficient_scope | 403 | no | The credential lacks a scope; details.requiredScopes lists them. |
quota_exceeded | 403 | no | Over one of the org's quotas, or a limit set for the credential; details names it. |
feature_not_enabled | 403 | no | Your organization does not have the feature the operation needs; details.feature names it. |
not_found | 404 | no | Not in your organization, or its tombstone expired. |
method_not_allowed | 405 | no | The path does not take that method; Allow lists those it does. |
idempotency_in_flight | 409 | yes | A request with the same key is still running. |
insufficient_capacity | 409 | yes | Not enough capacity for the whole request now; details gives the largest count that fits and alternatives. |
name_conflict | 409 | no | A live resource already has that name, hostname or port. |
invalid_state | 409 | no | The resource's status does not allow the operation. |
reservation_not_active | 409 | no | The reservation's window is not open. |
reservation_exhausted | 409 | no | The reservation has too few unused GPUs. |
offering_expired | 409 | no | The offering expired or was taken. |
payload_too_large | 413 | no | The body is larger than details.maxBytes. |
unsupported_media_type | 415 | no | The body is not application/json. |
idempotency_conflict | 422 | no | The key was already used with a different request. |
unsupported_combination | 422 | no | Each value is valid, but they do not work together. |
rate_limited | 429 | yes | Too many requests; wait for Retry-After. |
internal_error | 500 | yes | An unexpected failure; retrying with the same key is safe. |
unavailable | 503 | yes | The API cannot serve requests now. Running instances are not affected. |
Pagination
Every list takes pageSize (1 to 100, default 50) and pageToken, and returns { "items": [...], "nextPageToken": "..." }. Pass nextPageToken back unchanged, with the same filters, for the next page; it is absent on the last page and stays valid for at least an hour.
Versioning
Send Api-Version: 2026-10-15 on every request under /v1; a missing header returns 400 api_version_required. Within a version, the API only adds: new operations, optional fields and parameters, response fields, values of open enums and error codes. So:
- Ignore response fields you do not know.
- Accept enum values you do not know. Every enumerated value set is open.
- Changes that could break a client ship only under a new
Api-Versiondate, and each date is served for at least 24 months after its successor. A closing version sendsDeprecationandSunsetheaders.
Requests are strict: a field the API does not define returns 400 invalid_request with unknown_field, and null is never accepted; leave a field out to take its default.
Changes to 2026-10-15
- 2026-10-28: every create names its
location.POST /v1/instanceswithoutlocationnow returns400 invalid_requeston/location; the platform no longer picks a location for you. This one change breaks the rule above inside 2026-10-15. Send the location you want, such asus-west-1, or a location'sdefaultForfromGET /v1/locations. A create that does not fit returns409 insufficient_capacity, whosealternativesnow also list your size in the other locations where it fits.
Connect an AI agent
Give an AI agent Confidential Cloud through the MCP server, signed in with OAuth or an agent key.
List instances GET
Lists the org's instances, newest first. `terminated` tombstones are left out unless `status` includes `terminated` or `idempotencyKey` is set. Filters combine with AND, and repeated values of one filter combine with OR, except `label`, where every selector must match.