Vault
Error codes
Vault error statuses and retryability.
Every error response has the shape below; code is the stable error code and message is for people.
{
"request_id": "req_example",
"error": {
"code": "SECRET_CONFLICT",
"message": "A secret named GITHUB_TOKEN already exists",
"kind": "validation_failure",
"recovery": "none",
"retryable": false
}
}Error bodies include request_id for tracing. Compatibility endpoints use the following shape; 409 maps to conflict_error, and non-retryable errors carry x-should-retry: false.
{
"type": "error",
"error": {
"type": "conflict_error",
"message": "A credential with this name already exists"
},
"request_id": "req_example"
}| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| SECRET_NOT_FOUND | 404 | Secret absent, including lookup by an invalid name; check name or ID | validation_failure | none | no |
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| SECRET_CONFLICT | 409 | Name already exists on creation; rename or update the existing secret | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| VAULT_LIMIT_EXCEEDED | 400 | Active-secret limit exceeded; remove unused secrets | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
| SECRET_KIND_MISMATCH | 400 | Refreshing a static secret or another kind mismatch; use an OAuth secret | validation_failure | none | no |
| VALIDATE_UNSUPPORTED | 400 | Validating a static secret; only OAuth secrets support validation | validation_failure | none | no |
| SECRET_TOO_LARGE | 413 | Value exceeds 16384 bytes; reduce its size | validation_failure | none | no |
| RATE_LIMITED | 429 | Authorization or validation minute quota exceeded; wait for the next window | rate_limit | wait_then_retry | yes |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
| OAUTH_DISCOVERY_FAILED | 400 | OAuth metadata discovery failed; check the resource URL | validation_failure | continue_from_problem | no |
| OAUTH_REGISTRATION_UNSUPPORTED | 400 | Provider does not accept automatic client registration; add credentials manually | validation_failure | continue_from_problem | no |
| OAUTH_ISSUER_MISMATCH | 400 | Authorization issuer differs from the expected issuer; check the service URL | provider_upstream | retry_from_user | no |
| OAUTH_STATE_INVALID | 400 | Callback state missing, invalid or replayed; start authorization again | validation_failure | none | no |
| OAUTH_EXCHANGE_FAILED | 502 | Provider rejected the authorization-code exchange; authorize again | provider_upstream | retry_from_user | no |
| NOT_IMPLEMENTED | 501 | Capability unavailable; use a documented alternative | execution_failed | none | no |