API errors by operation

Every operation can return authentication, authorization, rate-limit and internal errors. Every write accepts an optional Idempotency-Key; conflicting reuse or an identical request still in progress returns 409. 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

Groups and encrypted access

All operations below require a human principal. Group collaboration is also plan-gated. Authorization and encrypted-material completion are separate: a successful membership or grant write can report pending material without being an HTTP failure. See the access model.

Operation	Important failure reasons
`POST /projects/{id}/group-grants/{groupId}`	`group_not_found`, `project_group_grant_role_invalid`, insufficient delegation, `plan_feature_locked`, `group_access_scope_changed`
`DELETE /projects/{id}/group-grants/{groupId}/{roleId}`	`group_not_found`, insufficient permission, `group_access_scope_changed`
`GET /projects/{id}/groups`	`project_not_found`, missing `groups:list`, `plan_feature_locked`
`POST /projects/{id}/groups`	`project_not_found`, invalid name, missing `groups:create`, `plan_feature_locked`
`PATCH /groups/{groupId}`	`group_not_found`, invalid name, missing `groups:update`, `plan_feature_locked`
`DELETE /groups/{groupId}`	`group_not_found`, insufficient permission on affected grants, `group_access_changed_retry`
`GET /groups/{groupId}/members`	`group_not_found`, missing `groups:list` or candidate-management permission, `plan_feature_locked`
`POST /groups/{groupId}/members`	`group_not_found`, invalid or ineligible member, insufficient delegation, `plan_feature_locked`, `group_access_changed_retry`
`DELETE /groups/{groupId}/members/{userId}`	`group_not_found`, insufficient permission on affected grants, `group_access_changed_retry`
`GET /records/{id}/group-grants`	`record_not_found`, missing `records:read`, `plan_feature_locked`
`GET /records/{id}/share-group-recipients/{groupId}`	`record_not_found`, `group_not_found`, missing `records:share-group`
`GET /records/by-project/{projectId}/missing-project-wrapper`	invalid project context, insufficient access
`GET /records/{id}/project-wrapped-dek`	invalid record context, insufficient access; material can be `null`
`POST /records/{id}/project-wrapped-dek`	invalid encrypted material, insufficient access, key-version conflict
`GET /projects/{projectId}/my-project-key`	invalid project context, insufficient access; material can be `null`
`GET /projects/{projectId}/member-public-keys`	invalid project context, insufficient access
`POST /projects/{projectId}/project-key`	invalid or incomplete encrypted batch, stale source or key version, insufficient access
`POST /projects/{projectId}/members/{userId}/project-key`	invalid sealed wrapper, changed recipient key or project version, insufficient access
`GET /record-group-key-pending`	invalid account context, insufficient access

Use the SDK reconciliation flow for encrypted batches. Do not construct wrappers from guessed recipients or retry stale encrypted material unchanged.

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, missing wrapper
`GET /records/{id}/versions`	`record_not_found`, `insufficient_permission`
`GET /records/{id}/audit`	`record_not_found`, invalid limit, `insufficient_permission`
`GET /records/{id}/audit/events`	`record_not_found`, `invalid_audit_filter`, `invalid_audit_date`, `invalid_list_cursor`, `cursor_and_offset_conflict`, `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_list_cursor`, `cursor_and_offset_conflict`, invalid pagination, `insufficient_permission`
`GET /audit/record-access`	`scope_id_required`, `invalid_list_cursor`, `cursor_and_offset_conflict`, invalid actions or pagination, `insufficient_permission`

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`, changed recipient manifest or key version
`POST /records/{id}/revoke/user`	`record_not_found`, `insufficient_permission`, `legacy_wrapper_provenance`; an already-absent unambiguous grant is a no-op
`POST /records/{id}/revoke/group`	`record_not_found`, `group_not_found`, `group_account_mismatch`, `legacy_wrapper_provenance`, insufficient permission; an already-absent grant is a no-op
`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

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

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

Getting Started

Guides

Reference

API errors by operation

Context and projects

Groups and encrypted access

Record reads and audit

Providers and provider credentials

Gateways and routing

Gateway tokens

Logs and usage

Service Account access

Debugging order

​Context and projects

​Groups and encrypted access

​Record reads and audit

​Record writes and sharing

​Providers and provider credentials

​Gateways and routing

​Gateway tokens

​Logs and usage

​Service Account access

​Debugging order

Context and projects

Groups and encrypted access

Record reads and audit

Record writes and sharing

Providers and provider credentials

Gateways and routing

Gateway tokens

Logs and usage

Service Account access

Debugging order