> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abliteration.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={"system"}
{
  "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:

```http theme={"system"}
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.