Skip to navigation

Errors and limits

Errors

Error envelopes vary by endpoint. Organization authorization failures can use a string error with a top-level code:

{
"error": "Insufficient scope",
"code": "insufficient_scope",
"requiredScopes": ["servers:read"]
}

Shared route errors can use a nested object:

{
"error": {
"code": "UNAUTHORIZED",
"message": "Missing or invalid Authorization header"
}
}

Storage errors can also include errorCode, message, and remediation. Use the HTTP status first, then the documented endpoint-specific code.

StatusInterpretation
400Invalid input or an unsupported operation/resource state
401Missing/invalid credentials or an inactive machine principal
403Missing scope, entitlement, or provider authorization
404Missing resource or a resource hidden from the caller
409State conflict, duplicate resource, or incompatible idempotency replay
422Provider or organization prerequisite/availability failure
429Throttled; honor Retry-After when supplied
500Internal error
503Dependency unavailable or application maintenance

Rate limits

OperationLimitIdentity
Token exchange60/minuteTrusted client IP and valid API key, independently
API-key introspection120/minuteTrusted client IP and matched API key, independently
Invitation creation (development contract)20/minuteOrganization and actor

Throttled responses include Retry-After. Some auth responses also expose X-RateLimit-Remaining and X-RateLimit-Reset. There is no single universal request quota across this reference.

Retry behavior

Cache and reuse an unexpired exchanged JWT to avoid unnecessary exchange calls. Retry read requests after transient failures with bounded backoff. Before retrying a mutation, inspect its resource and jobs; most infrastructure endpoints do not provide an idempotency-key contract.

Invitation creation requires Idempotency-Key. Reuse that key only with the same body. A changed body returns a conflict, and terminal replay omits the capability URL.

During application maintenance, affected API requests return 503 with code: "MAINTENANCE_MODE", Retry-After: 60, and Cache-Control: no-store.