Error Codes | HashiCorp

Code	Triggered by
`HASHICORP_INVALID_CONFIGURATION`	A required config key is missing or malformed — no `vaultAddress`, `authMethod` not `token`/`appRole`, missing `credentialID`, missing `mount` on a Secrets op, or a `namespace` value that fails the slash-path pattern. Fails before any HTTP call.
`HASHICORP_CREDENTIAL_NOT_FOUND`	`authMethod: "token"` and the resolved BizFirst credential record did not yield a usable Vault token.
`HASHICORP_AUTH_FAILED`	`authMethod: "appRole"` and the AppRole login (`role_id`/`secret_id` exchange) was rejected by Vault, or the credential record had no usable AppRole pair. Also the default fallback for an unrecognized token-service error status.
`HASHICORP_TOKEN_EXPIRED`	A Token operation received a Vault 403 whose error text specifically indicates the token has expired.
`HASHICORP_PERMISSION_DENIED`	Vault returned 403 and it isn't one of the more specific token/lease cases above — the resolved identity lacks the Vault policy needed for this call.
`HASHICORP_SECRET_NOT_FOUND`	A Secrets operation received a 404 from Vault (path doesn't exist at the given mount/version).
`HASHICORP_CAS_MISMATCH`	`secrets/write` with a `cas` value received a 400 whose error text references check-and-set — someone else wrote a newer version first.
`HASHICORP_LEASE_NOT_FOUND`	A Lease operation received a 400/404 that isn't specifically a not-renewable error — the lease ID doesn't exist or already expired.
`HASHICORP_LEASE_NOT_RENEWABLE`	`lease/renew` (or `token/renewSelf`/`renewByAccessor`) received an error whose text says the lease/token isn't renewable — some Vault-issued leases and tokens are marked non-renewable by policy.
`HASHICORP_SEALED`	Any authenticated call received Vault's 503 — the vault is sealed and cannot serve authenticated requests. Run `system/sealStatus` to confirm.
`HASHICORP_VAULT_UNREACHABLE`	No HTTP response was received at all — timeout, DNS failure, connection refused, or TLS failure. This is `HashiCorpApiException`'s status-code-`0` sentinel, used identically on both authenticated and unauthenticated (System) calls.
`HASHICORP_UPSTREAM_ERROR`	Catch-all: a genuine Vault 5xx after retries are exhausted, a response Vault returned but this node couldn't parse into the expected shape, or an unexpected exception during the call.

Retry Behavior

HashiCorpApiClientOptions configures MaxRetries (default 2) and InitialRetryDelay (default 1 second, doubling per attempt) for retryable failures — a 429 from a fronting proxy, or a 5xx status other than the ones Vault documents as sealed/standby. Sealed (503) and standby-role codes are treated as meaningful state, not transient failures, so they are not blindly retried.

Every error result carries both a code and a message. The message is built from Vault's own errors array where one exists (HashiCorpApiException.VaultErrors), so the underlying Vault-side reason is preserved rather than replaced with a generic string.

See Troubleshooting for the practical fix that goes with each of these.