Docs

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.

WhatLimit
Creates (POST /v1/instances)10 a minute
Every other request600 a minute
Requests without a valid credential, per source address60 a minute
New connections to attest endpoints, per source address1 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_flight with Retry-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 on status and retryable.
  • params lists every problem with the request at once, each at a JSON Pointer into the body or a parameter name, with allowedValues when the accepted values are a known set.
  • details carries the numbers you need to recover, documented with each code.
  • Quote requestId (also in the X-Request-ID header) 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.

CodeStatusRetryMeaning
invalid_request400noThe request is malformed or a value is invalid. params lists every violation.
api_version_required400noThe Api-Version header is missing.
unsupported_api_version400noThe API does not serve that version; details.supportedVersions lists those it does.
idempotency_key_required400noA POST was sent without Idempotency-Key.
unauthenticated401noThe credential is missing, malformed, unknown or revoked, or the token expired.
key_expired401noThe API key expired.
payment_required402noYour organization has no payment method, or its invoices are unpaid, or billing has not opened yet; an owner adds one in Settings → Billing.
insufficient_scope403noThe credential lacks a scope; details.requiredScopes lists them.
quota_exceeded403noOver one of the org's quotas, or a limit set for the credential; details names it.
feature_not_enabled403noYour organization does not have the feature the operation needs; details.feature names it.
not_found404noNot in your organization, or its tombstone expired.
method_not_allowed405noThe path does not take that method; Allow lists those it does.
idempotency_in_flight409yesA request with the same key is still running.
insufficient_capacity409yesNot enough capacity for the whole request now; details gives the largest count that fits and alternatives.
name_conflict409noA live resource already has that name, hostname or port.
invalid_state409noThe resource's status does not allow the operation.
reservation_not_active409noThe reservation's window is not open.
reservation_exhausted409noThe reservation has too few unused GPUs.
offering_expired409noThe offering expired or was taken.
payload_too_large413noThe body is larger than details.maxBytes.
unsupported_media_type415noThe body is not application/json.
idempotency_conflict422noThe key was already used with a different request.
unsupported_combination422noEach value is valid, but they do not work together.
rate_limited429yesToo many requests; wait for Retry-After.
internal_error500yesAn unexpected failure; retrying with the same key is safe.
unavailable503yesThe 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-Version date, and each date is served for at least 24 months after its successor. A closing version sends Deprecation and Sunset headers.

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/instances without location now returns 400 invalid_request on /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 as us-west-1, or a location's defaultFor from GET /v1/locations. A create that does not fit returns 409 insufficient_capacity, whose alternatives now also list your size in the other locations where it fits.

On this page