Error Handling¶
All exceptions raised by VaultSDK for a failed server request derive from VaultError.
from cps_vault_sdk import (
VaultError,
SecretAlreadyExistsError,
SecretNotFoundError,
ValidationError,
)
| Exception | Raised when | HTTP status |
|---|---|---|
VaultError |
Base class for all SDK errors from a failed server request. Catch this to handle any CPS-Vault-related failure generically. | any non-2xx not covered below |
SecretNotFoundError |
The server has no secret with the given name. | 404 |
SecretAlreadyExistsError |
create()'s internal fallback to put() on a 409 conflict itself also returns 409 (should not normally happen — create() transparently retries as an update on a plain 409). |
409 |
ValidationError |
The server rejected the request body as malformed (e.g. missing required field, invalid ttl format). |
400 |
Two transient statuses are not mapped to a dedicated exception - they surface as a plain
VaultError (after the SDK's automatic retries are exhausted) with status_code set:
status_code |
Meaning | What to do |
|---|---|---|
429 |
Too many requests - your source IP exceeded the WAF per-IP rate limit, or API Gateway throttling kicked in. |
Back off and retry; spread load across time. Limits are generous (10,000 requests per 5 minutes per IP by default). |
503 |
identity provider unavailable - STS did not answer within 3 seconds, so the identity proof could not be verified. |
Retry; the SDK already retries this automatically. |
Every VaultError (and its subclasses) carries:
status_code: int | None— the HTTP status code returned by the server, if any.response: requests.Response | None— the rawrequestsresponse object, for inspecting headers/body if needed.
Example¶
from cps_vault_sdk import VaultSDK, SecretNotFoundError, ValidationError, VaultError
sdk = VaultSDK()
try:
value = sdk.fetch("my-app/db-password")
except SecretNotFoundError:
print("secret does not exist yet")
except ValidationError as e:
print(f"bad request: {e} (status={e.status_code})")
except VaultError as e:
print(f"vault call failed: {e} (status={e.status_code})")
Notes on create()¶
create() automatically falls back to put() if the secret already exists (a 409 on the
initial POST), so a plain "create-or-update" flow doesn't need to catch anything special. A
SecretAlreadyExistsError from create() only surfaces if that fallback put() call itself also
fails with 409, which should not happen in normal use.