Skip to content

Errors

Every failure mode a caller might branch on has its own type, so a backend can map exceptions to HTTP status codes without string matching.

Suggested HTTP mapping

Exception HTTP
RequestNotFound, UnknownPolicy 404
SubjectConstraintViolation 422
PolicyMismatch, IdempotencyConflict 409
ConcurrencyExhausted (after retries) 503
ChallengeExpired, RequestExpired 410
SignatureInvalid 400
KeyNotAuthorized, KeyExpiredOrRevoked, SeparationOfDutiesViolation 403
StoreError 502 / 503
LedgerTampered (any subtype), VerificationFailed 500 + alert a human

Hierarchy

Typed exception hierarchy.

Every failure mode a caller might branch on has its own type, so a BFF can map them to HTTP status codes without string matching. Suggested mapping:

=================================== ====== Exception HTTP =================================== ====== RequestNotFound 404 UnknownPolicy 404 SubjectConstraintViolation 422 PolicyMismatch 409 IdempotencyConflict 409 LedgerConflict (after retries) 503 ChallengeExpired 410 SignatureInvalid 400 KeyNotAuthorized 403 KeyExpiredOrRevoked 403 SeparationOfDutiesViolation 403 RequestExpired 410 LedgerTampered (any subtype) 500 + page someone =================================== ======

ApprovoError

Bases: Exception

Base class for all approvo errors.

PolicyMismatch

Bases: ApprovoError

The policy pinned by the request no longer matches the stored policy.

IdempotencyConflict

Bases: ApprovoError

The same idempotency key was reused with a different payload.

ChallengeExpired

Bases: ApprovoError

A signing challenge was submitted after its expiry.

LedgerConflict

Bases: ApprovoError

Two writers raced to append the same sequence number.

Expected under concurrency; the service retries automatically. Escaping this exception means retries were exhausted — treat as backpressure.

ConcurrencyExhausted

Bases: LedgerConflict

Append retries were exhausted under sustained write contention.

StoreError

Bases: ApprovoError

The underlying datastore failed. Wraps driver exceptions.

SigningError

Bases: ApprovoError

A signing backend failed to produce a signature.

KeyProviderError

Bases: SigningError

A :class:~approvo.crypto.keyprovider.KeyProvider could not resolve or load a key. Wraps KMS / Vault / filesystem driver exceptions.

KeyResolutionError

Bases: SigningError

A :class:~approvo.crypto.resolver.KeyResolver produced no key reference for the given signing context.

UnsupportedAlgorithmError

Bases: SigningError

The signature scheme on a key or signer is not in the registry.

LedgerTampered

Bases: ApprovoError

The ledger failed integrity verification. Always an incident.

ChainBroken

Bases: LedgerTampered

An entry's prev_hash does not match the previous entry.

EntryHashMismatch

Bases: LedgerTampered

An entry's recorded hash does not match its recomputed hash.

SeqGap

Bases: LedgerTampered

Sequence numbers are not contiguous.

CheckpointUnverified

Bases: LedgerTampered

A checkpoint signature or root hash failed to verify.

ConsistencyFailure

Bases: LedgerTampered

The log is not a consistent extension of a previously trusted checkpoint.

VerificationFailed

Bases: ApprovoError

One or more checks in a verification report failed.