Administration API errors

Administration endpoints return one JSON error envelope:

{
  "error": {
    "message": "The request could not be completed.",
    "type": "validation_error",
    "param": "page",
    "code": "invalid_page",
    "request_id": "req_example"
  }
}

Do not branch on message. Use the HTTP status and stable code.

Status	Meaning	Action
`400`	Invalid request or cursor	Correct the request; do not retry unchanged
`401`	Missing, invalid, expired, or revoked Admin API key	Replace the credential
`403`	The key lacks the required permission or organization ownership	Use an authorized key
`404`	The resource is absent from the key’s organization	Check the resource ID and organization
`409`	Resource or idempotency conflict	Resolve the reported conflict before retrying
`413`	Request body exceeds the Administration API limit	Reduce the body to 64 KiB or less
`422`	Invalid body, time range, grouping, or result size	Correct the reported parameter
`429`	Credential, organization, or concurrency limit exceeded	Honor `Retry-After` and retry with backoff
`503`	Service temporarily unavailable	Retry with exponential backoff

Rate-limit headers

Successful and rate-limited responses include the policy that determined the request allowance:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1790812860
X-RateLimit-Scope: credential
X-RateLimit-Metric: requests

A 429 response also includes Retry-After. The scope is credential or organization; the metric is requests or concurrent_requests.

Credential errors

Admin API keys and ak_... Project API keys are not interchangeable. Sending a Project API key to an Administration endpoint returns 401 invalid_admin_credential. Sending an Admin API key to a model endpoint also fails authentication.

Idempotency errors

idempotency_conflict: the same Idempotency-Key was used with a different request.
idempotency_in_progress: an earlier request with the same key has not completed.
idempotency_expired: the 24-hour replay window has ended. Use a new key for the next operation.
idempotency_reconciliation_required: an earlier Admin API-key creation could not be confirmed. Review the organization’s Admin API keys before retrying with a new idempotency key.

Use a stable key for retries of one logical operation. Use a new key for a new operation. If Admin API-key creation returns 503, retry with the same idempotency key. If a later retry returns 409 idempotency_reconciliation_required, list the organization’s Admin API keys. If the requested key exists but its secret was not returned, revoke it and create a replacement. If it does not appear, retry with a new idempotency key. Contact support if you cannot confirm the result.

Policy errors

policy_revision_conflict: the policy changed after the revision you read. Retrieve the policy, apply your change to the latest draft, and retry with its current revision.
policy_state_conflict: the requested action is not valid for the policy’s current lifecycle state. Retrieve the policy before choosing the next action.
invalid_policy: the draft does not satisfy the policy rules. Correct the reported field before retrying.
invalid_policy_project: one or more project IDs are unavailable to the organization that owns the Admin API key.

Start here

Inference API