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.