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
- 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
requestIdwhen the same server failure continues.