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

# API errors by operation

> Likely failure reasons for every public AIRCTRL API operation.

export function AirctrlWordmark() {
  return <span className="airctrl-wordmark" aria-label="AIRCTRL">
      <span aria-hidden="true" className="airctrl-wordmark-air">AIR</span>
      <span aria-hidden="true" className="airctrl-wordmark-ctrl">CTRL</span>
    </span>;
}

Every operation can return authentication, authorization, rate-limit and internal errors. The table below adds resource-specific failures. The API Reference remains the source for exact fields and HTTP response schemas.

## Context and projects

| Operation                      | Important failure reasons                                                           |
| ------------------------------ | ----------------------------------------------------------------------------------- |
| `GET /accounts`                | `missing_bearer_token`, `invalid_pat`, `pat_expired`                                |
| `GET /projects`                | `not_account_member`, invalid account ID or query values                            |
| `GET /projects/{id}`           | `project_not_found`, `not_authorized`                                               |
| `POST /projects`               | invalid name, `plan_limit_reached`, `insufficient_permission`, idempotency conflict |
| `PATCH /projects/{id}`         | `project_not_found`, invalid replacement values, `insufficient_permission`          |
| `PATCH /projects/{id}/archive` | `project_not_found`, `insufficient_permission`, conflicting state                   |

## Record reads and audit

| Operation                             | Important failure reasons                                                     |
| ------------------------------------- | ----------------------------------------------------------------------------- |
| `GET /records`                        | invalid pagination or account context, `not_authorized`                       |
| `GET /records/by-project/{projectId}` | `project_not_found`, invalid pagination, `not_authorized`                     |
| `GET /records/{id}`                   | `record_not_found`, `not_authorized`, missing record wrapper                  |
| `POST /records/{id}/read`             | `record_not_found`, invalid scope or environment, missing wrapper             |
| `GET /records/{id}/versions`          | `record_not_found`, `insufficient_permission`                                 |
| `GET /records/{id}/audit`             | `record_not_found`, invalid limit, `insufficient_permission`                  |
| `GET /audit/record-anomalies`         | `scope_id_required`, invalid scope, `insufficient_permission`                 |
| `GET /audit/record-activity`          | `invalid_day`, `scope_id_required`, `insufficient_permission`                 |
| `GET /audit/record-alerts`            | `scope_id_required`, invalid pagination, `insufficient_permission`            |
| `GET /audit/record-access`            | `scope_id_required`, invalid actions or pagination, `insufficient_permission` |

## Record writes and sharing

| Operation                                   | Important failure reasons                                                                                  |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `POST /records`                             | `project_not_found`, `project_not_keyed`, `record_name_exists`, key-version conflict, idempotency conflict |
| `POST /records/{id}/version`                | `record_not_found`, missing wrapper, invalid encrypted payload, key-version conflict                       |
| `PATCH /records/{id}`                       | `record_not_found`, invalid metadata, `insufficient_permission`                                            |
| `PATCH /records/{id}/archive`               | `record_not_found`, conflicting state, `insufficient_permission`                                           |
| `POST /records/{id}/transfer-ownership`     | `record_not_found`, `target_not_a_member`, `insufficient_permission`                                       |
| `POST /records/{id}/rollback`               | `record_not_found`, invalid version, missing wrapper, idempotency conflict                                 |
| `POST /records/{id}/rotate`                 | `record_not_found`, invalid wrappers, key-version conflict, idempotency conflict                           |
| `POST /records/{id}/share/user`             | `record_not_found`, `target_not_a_member`, `recipient_public_key_not_found`                                |
| `POST /records/{id}/share/group`            | `record_not_found`, `group_not_found`, `group_account_mismatch`, `group_project_mismatch`                  |
| `POST /records/{id}/revoke/user`            | `record_not_found`, missing direct grant, `insufficient_permission`                                        |
| `POST /records/{id}/revoke/group`           | `record_not_found`, `group_not_found`, missing group grant                                                 |
| `POST /records/{id}/revoke/service-account` | `record_not_found`, missing Service Account grant, `insufficient_permission`                               |

## Providers and provider credentials

| Operation                                | Important failure reasons                                                                 |
| ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| `GET /providers`                         | authentication failure or temporary service failure                                       |
| `GET /provider-credentials`              | `not_account_member`, `insufficient_permission`                                           |
| `POST /provider-credentials`             | `provider_not_found`, rejected provider key, `base_url_not_allowed`, `plan_limit_reached` |
| `GET /provider-credentials/{id}/models`  | `credential_not_found`, revoked credential, provider validation failure                   |
| `POST /provider-credentials/{id}/rotate` | `credential_not_found`, rejected replacement key, `base_url_not_allowed`                  |
| `PATCH /provider-credentials/{id}`       | `credential_not_found`, invalid label, `insufficient_permission`                          |
| `DELETE /provider-credentials/{id}`      | `credential_not_found`, `insufficient_permission`                                         |

## Gateways and routing

| Operation                                          | Important failure reasons                                                   |
| -------------------------------------------------- | --------------------------------------------------------------------------- |
| `GET /gateways`                                    | `project_not_found`, invalid project context, `not_authorized`              |
| `GET /gateways/{id}`                               | `gateway_not_found`, `not_authorized`                                       |
| `POST /gateways`                                   | `project_not_found`, invalid slug, foreign credential, `plan_limit_reached` |
| `PATCH /gateways/{id}`                             | `gateway_not_found`, invalid provider or model, `insufficient_permission`   |
| `DELETE /gateways/{id}`                            | `gateway_not_found`, `insufficient_permission`                              |
| `POST /gateways/{id}/credentials`                  | `gateway_not_found`, `credential_not_found`, account mismatch               |
| `DELETE /gateways/{id}/credentials/{credentialId}` | `gateway_not_found`, `credential_not_found`, conflicting routing state      |
| `PATCH /gateways/{id}/settings`                    | `gateway_not_found`, invalid limit, window, guardrail or cache value        |
| `GET /gateways/{id}/otel-export`                   | `gateway_not_found`, `insufficient_permission`                              |
| `PATCH /gateways/{id}/otel-export`                 | `gateway_not_found`, invalid endpoint or headers, `insufficient_permission` |

## Gateway tokens

| Operation                                       | Important failure reasons                                                                         |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `GET /gateways/{id}/tokens`                     | `gateway_not_found`, `not_authorized`                                                             |
| `POST /gateways/{id}/tokens`                    | `gateway_not_found`, `service_account_not_in_account`, `service_account_inactive`, invalid limits |
| `PATCH /gateways/{id}/tokens/{tokenId}`         | `gateway_not_found`, `token_not_found`, invalid name                                              |
| `DELETE /gateways/{id}/tokens/{tokenId}/revoke` | `gateway_not_found`, `token_not_found`, conflicting token state                                   |
| `DELETE /gateways/{id}/tokens/{tokenId}`        | `gateway_not_found`, `token_not_found`, `insufficient_permission`                                 |

## Logs and usage

| Operation                         | Important failure reasons                                                     |
| --------------------------------- | ----------------------------------------------------------------------------- |
| `GET /gateways/{id}/logs`         | `gateway_not_found`, invalid filters or pagination, `not_authorized`          |
| `GET /gateways/{id}/logs/{logId}` | `gateway_not_found`, `log_not_found`, missing body-read permission            |
| `GET /gateways/{id}/key-access`   | `gateway_not_found`, invalid outcome or pagination, `insufficient_permission` |
| `GET /usage/logs`                 | `project_not_found`, invalid filters or pagination, `insufficient_permission` |
| `GET /usage/logs/{logId}`         | `project_not_found`, `log_not_found`, missing body-read permission            |
| `GET /usage/spend`                | `project_not_found`, missing spend-read permission                            |
| `GET /usage/metrics`              | `project_not_found`, invalid date or bucket, `insufficient_permission`        |

## Service Account access

| Operation                            | Important failure reasons                                                                       |
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `GET /service-accounts`              | `not_account_member`, `insufficient_permission`                                                 |
| `POST /service-accounts/{id}/grants` | `record_not_found`, Service Account/account mismatch, inactive Service Account, invalid wrapper |

## Debugging order

1. Check HTTP status and `error.code`.
2. Read the specific reason in `error.message`.
3. Confirm identity mode, account context and exact resource ID.
4. Check RBAC and direct record or project access in the dashboard.
5. Retry only temporary failures.
6. Keep `requestId` when the same server failure continues.

Do not probe neighboring IDs after a not-found or authorization response. <AirctrlWordmark /> may intentionally hide whether an inaccessible resource exists.