Middleware Errors

These are raised by the middleware before the request reaches the store service, so they are not tied to any one operation — any call can return them.

Error	Meaning
unauthenticated	The token has expired.
unauthorized	The caller does not have the right to call this API.
unauthorized_delegation	The caller does not have the right to call the API with the user_id passed in the x-patron-id header.
otp_required	The call requires an OTP.

Delegated calls and x-patron-id

x-patron-id carries the user_id the caller is acting on behalf of. When it is present the middleware runs a delegation check on top of the normal authorization check:

Error	What it tells the caller
unauthorized	You can't make this call at all.
unauthorized_delegation	You can't make this call for that user.

Still to document

• HTTP status and wire format — the table above gives the codes, not the response envelope they arrive in.
• Which calls can raise otp_required, and how the client supplies the OTP and retries.
• Whether x-patron-id is optional (omitted for self-service) or always sent.
• Whether unauthenticated covers only expiry, or also malformed and revoked tokens.