Administration API errors

Error envelopes, status codes, retry guidance, and rate-limit headers for the Abliteration Administration API.

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.