Skip to content

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 raw requests response 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.