Problem Details type URIs - Agent Volumes

Agent Volumes Registry API errors use RFC 9457 Problem Details. Each type URI is a stable machine-readable identifier under https://agentvolumes.org/problems/<slug>. This page describes the stable problem type URI set. Release-specific API and schema documentation remains archived under /spec/<version>/....

Problem type URI pattern

https://agentvolumes.org/problems/<slug>

Switch on the type URI when handling Agent Volumes Registry API errors. Do not switch on title, because implementations can vary or localize human-readable titles.

Stable problem types

Problem type	Status	Meaning
`authentication-required`	401	Bearer authentication is missing or invalid.
`authorization-failed`	403	The caller, request context, or requested resource is not permitted by authorization or access policy.
`not-found`	404	The requested resource does not exist or is not visible to the caller.
`validation-failed`	400	Request payload, parameters, manifest, or metadata failed validation.
`invalid-manifest`	400	A submitted `volume.toml` is structurally or semantically invalid.
`invalid-archive`	400	A submitted hosted archive violates the v0.1 archive transport profile.
`identity-mismatch`	409	A package identity disagrees with its route, manifest, or metadata.
`version-conflict`	409	The target version already exists or cannot be reused.
`digest-mismatch`	400	Submitted or resolved bytes do not match the declared digest.
`subject-binding-mismatch`	400	A trust artifact does not bind to the intended release subject.
`inconsistent-registry-state`	409	Index, exact metadata, or trust metadata cannot be reconciled.
`upload-expired`	410	An upload intent expired before finalization.
`missing-uploaded-bytes`	400	Finalization was requested before upload bytes were available.
`invalid-upload-state`	409	The upload intent is not in a state that can be finalized.
`idempotency-conflict`	409	A reused idempotency key conflicts with an earlier request.
`payload-too-large`	413	The submitted payload or declared upload size exceeds the bibliotheca’s accepted limit.
`unsupported-media-type`	415	The submitted payload media type is not supported.
`permission-escalation`	400	Component permissions exceed the parent volume permission boundary.
`rate-limited`	429	The request was rate limited.

Versioning policy

The problem URI set is closed for the Agent Volumes v0.1 portable baseline. Patch releases can clarify problem documentation without changing the meaning of an existing type URI. Incompatible problem semantics require a new problem slug or a new versioned problem URI.

Release archives

Canonical sources