# Error codes

Documentation version: 0.3.1.

Every failure a secret operation can report maps to one stable, `snake_case`
code. Codes are a compatibility contract: they are **append-only**, never
renamed and never reused. Messages are for humans and may change.

Where you meet them:

- The CLI exits with status `1` and, in `--output json` mode, prints
  `{"error":{"code":"…","message":"…"}}` on stderr.
- Audit rows record the code in their `detail` column, never a value.
- SDKs map codes to typed errors, each carrying a hint that says what to do.

Messages carry names, versions and timestamps only. No error ever contains
a secret value.

| Code | Meaning | Message format | Retry later? |
|------|---------|----------------|--------------|
| `not_found` | The named secret does not exist (and is not in the deleted state). | `secret '{name}' was not found` |  |
| `version_not_found` | The secret exists but the requested version does not. | `version '{version}' of secret '{name}' was not found` |  |
| `deleted` | The secret has been soft-deleted and must be recovered before use. | `secret '{name}' is deleted; recover it before use` |  |
| `deleted_conflict` | A soft-deleted secret with this name blocks creating a new one. | `a deleted secret named '{name}' exists; recover or purge it first` |  |
| `not_deleted` | Recovery or purge was requested for a secret that is not deleted. | `secret '{name}' is not in the deleted state` |  |
| `disabled` | The version is disabled by policy. | `secret '{name}' version '{version}' is disabled` |  |
| `not_yet_valid` | The version's activation time has not been reached. | `secret '{name}' version '{version}' is not valid before {not_before}` |  |
| `expired` | The version's expiry time has passed. | `secret '{name}' version '{version}' expired on {expires_on}` |  |
| `invalid_name` | The name does not satisfy the naming rules. | `invalid name '{name}': {reason}` |  |
| `invalid_argument` | A caller-supplied argument was rejected. | `invalid argument: {0}` |  |
| `permission_denied` | The caller is authenticated but not authorised. | `permission denied: {0}` |  |
| `locked` | The vault could not be opened (no key for this machine, a wrong recovery key, ...). | `vault is locked: {0}` |  |
| `vault_not_found` | The vault does not exist. | `vault '{name}' was not found` |  |
| `vault_exists` | A vault with this name already exists. | `vault '{name}' already exists` |  |
| `manifest` | A project manifest could not be read or is invalid. | `manifest error: {0}` |  |
| `crypto` | A cryptographic operation failed (authentication failure, bad key, ...). | `cryptographic failure: {0}` |  |
| `storage` | The storage backend failed. | `storage failure: {0}` |  |
| `io` | An I/O operation failed. | `i/o failure: {0}` |  |
| `unsupported` | The backend does not implement this operation. | `unsupported operation: {0}` |  |
| `migration_required` | The vault file was written by an earlier release, in an on-disk format this release does not read. There is no migration: the format changed with how a vault is opened and checked, so the vault is recreated (the code keeps its old name; codes are append-only). The file is left as it is, for the release that wrote it. | `vault '{name}' was written by an earlier release (schema {schema}); this release cannot read it and has not changed it: keep the file for that release by moving it out of the vaults folder, then recreate the vault with `sourceorrery setup` and set its secrets from the old file (the Upgrading guide)` |  |
| `vault_mismatch` | The file found for the requested vault holds a different vault: it was renamed or copied from that vault, or swapped in by someone who can write the vault directory. Refused so that a vault is never served under another vault's name. | `the file for vault '{requested}' holds the vault '{found}'` |  |
| `backup_passphrase` | The passphrase did not open an encrypted backup file. No operation produces it since `vault export` replaced backups (ADR 0009); it stays because codes are never taken back. | `the passphrase does not open this backup` |  |
| `backup_format` | A backup file was written in a newer format than the build read. No operation produces it since `vault export` replaced backups (ADR 0009); it stays because codes are never taken back. | `backup format {version} is newer than this build understands; upgrade sourceorrery` |  |
| `unauthenticated` | A remote provider has no credentials for this process, or they have expired. `reason` is the provider's own description of what is missing: never a credential, nor any part of one. | `not authenticated to {provider}: {reason}` |  |
| `provider_unavailable` | A remote provider could not be reached or answered with a server error. Transient: the same call may succeed later. | `{provider} is unavailable: {reason}` |  |
| `rotation` | A rotation step was asked for in a state that does not allow it: a validated candidate is already waiting, there is nothing to activate or retire, or the grace period has not ended. The message carries versions and times only. | `rotation of '{name}': {reason}` |  |
| `outcome_unknown` | A change was sent to a remote provider and whether the provider made it is not known: its answer was lost, it failed in a way that does not prove nothing changed, or the provider made it and the vault could not record it (ADR 0011). Not transient: check the secret at the provider before repeating the change. `at` names the provider or the vault's connection; `reason` says what is known, never a value. | `the change may have been made at {at}: {reason}` |  |

*Retry later* marks codes for which `SecretError::is_transient` is true:
calling again later could succeed without administrative action.

Source of truth: [`crates/sourceorrery-core/src/error.rs`](https://github.com/Netizine/sourceorrery/blob/main/crates/sourceorrery-core/src/error.rs).
