Registry API error codes and responses

All Agent Volumes Registry API error responses use RFC 9457 Problem Details with the application/problem+json content type. Each error has a type URI that identifies the problem category, a human-readable title, and an HTTP status code. An optional detail field provides context-specific information about the specific failure. The type URI is the stable machine-readable identifier your client should switch on — not the title, which may vary.

Error response format

{
  "type": "https://agentvolumes.org/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Volume '@acme/research-agent-pack' does not exist.",
  "instance": "/api/v1/volumes/@acme/research-agent-pack/1.4.0"
}

Field	Type	Description
`type`	string (URI)	Machine-readable problem type identifier. Always present.
`title`	string	Human-readable problem title. Always present.
`status`	integer	HTTP status code repeated in the body. Always present.
`detail`	string	Context-specific human-readable explanation. Optional.
`instance`	string (URI reference)	Reference to the specific occurrence. Optional.

Problem type URIs

All Agent Volumes problem type URIs follow the pattern:

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

See the Problem Details type URI index for stable public documentation pages for every closed v0.1 problem slug.

Complete error table

Slug	Status	Meaning
`authentication-required`	401	Bearer authentication is missing, malformed, unknown, expired, or revoked
`authorization-failed`	403	The authenticated caller is not authorized for the requested operation or resource
`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 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

The problem type set above is closed for the v0.1 portable baseline. Bibliothecas must not introduce additional problem types in the https://agentvolumes.org/problems/ namespace.

Endpoint-to-error mapping

Endpoint	Common problem slugs
`GET /api/v1/search`	`validation-failed`, `rate-limited`
`GET /api/v1/index/volumes/...`	`not-found`, `inconsistent-registry-state`, `rate-limited`
`GET /api/v1/volumes/{name}/{version}`	`authorization-failed`, `not-found`, `inconsistent-registry-state`, `rate-limited`
`POST /api/v1/volumes/{name}`	`authentication-required`, `authorization-failed`, `validation-failed`, `version-conflict`, `idempotency-conflict`, `rate-limited`
`POST /api/v1/volumes/{name}/uploads/{uploadId}/finalize`	`authentication-required`, `authorization-failed`, `not-found`, `invalid-manifest`, `invalid-archive`, `digest-mismatch`, `identity-mismatch`, `missing-uploaded-bytes`, `invalid-upload-state`, `idempotency-conflict`, `upload-expired`, `payload-too-large`, `unsupported-media-type`, `permission-escalation`, `rate-limited`
`GET /api/v1/volumes/{name}/{version}/trust/summary`	`not-found`, `inconsistent-registry-state`, `rate-limited`
`GET /api/v1/volumes/{name}/{version}/trust/detail`	`not-found`, `inconsistent-registry-state`, `rate-limited`
`POST /api/v1/volumes/{name}/{version}/trust/uploads`	`authentication-required`, `authorization-failed`, `not-found`, `subject-binding-mismatch`, `idempotency-conflict`, `payload-too-large`, `unsupported-media-type`, `rate-limited`
`POST /api/v1/volumes/{name}/{version}/trust/uploads/{uploadId}/finalize`	`authentication-required`, `authorization-failed`, `not-found`, `missing-uploaded-bytes`, `invalid-upload-state`, `digest-mismatch`, `subject-binding-mismatch`, `idempotency-conflict`, `upload-expired`, `payload-too-large`, `unsupported-media-type`, `rate-limited`
`GET /api/v1/advisories`	`validation-failed`, `rate-limited`
`GET /api/v1/advisories/{advisoryId}`	`not-found`, `rate-limited`
`GET /api/v1/capabilities`	`rate-limited`

Authentication and authorization errors

A 401 always means the token itself is the problem — it is missing, malformed, unknown, expired, or revoked:

{
  "type": "https://agentvolumes.org/problems/authentication-required",
  "title": "Authentication required",
  "status": 401
}

A 403 means authentication succeeded but the token lacks permission for the specific operation or resource:

{
  "type": "https://agentvolumes.org/problems/authorization-failed",
  "title": "Authorization failed",
  "status": 403,
  "detail": "This token is not authorized to publish to @acme/my-volume."
}

Rate limit errors

When you exceed a rate limit tier, you receive:

{
  "type": "https://agentvolumes.org/problems/rate-limited",
  "title": "Rate limited",
  "status": 429
}

See Overview for the recommended rate limit tiers (anonymous, authenticated, and CI token).

Idempotency key errors

If you pass both an Idempotency-Key header and an idempotencyKey body field with different values, or if you reuse a key with conflicting request parameters, you receive:

{
  "type": "https://agentvolumes.org/problems/idempotency-conflict",
  "title": "Idempotency conflict",
  "status": 409
}

When only one form is present (header or body field), that value is used as the idempotency key. The header form is the preferred portable API surface.

Upload lifecycle errors

Scenario	Problem slug	Status
Finalize called before bytes were uploaded	`missing-uploaded-bytes`	400
Upload intent expired before finalize	`upload-expired`	410
Intent is in a state that cannot be finalized	`invalid-upload-state`	409
Uploaded bytes don’t match declared digest	`digest-mismatch`	400
Trust artifact doesn’t bind to the release subject	`subject-binding-mismatch`	400

Permission escalation errors

If a volume.toml declares a component with permissions broader than its parent volume permits and a bibliotheca detects that escalation during validation, it can return:

{
  "type": "https://agentvolumes.org/problems/permission-escalation",
  "title": "Permission escalation",
  "status": 400,
  "detail": "Component 'arxiv-search' declares network=read-write but the volume permits only network=read."
}

Clients must fail before submission when they detect permission escalation locally. Do not rely solely on the server to catch this — validate your volume.toml before calling the publish endpoint.

​Error response format

​Problem type URIs

​Complete error table

​Endpoint-to-error mapping

​Authentication and authorization errors

​Rate limit errors

​Idempotency key errors

​Upload lifecycle errors

​Permission escalation errors

Error response format

Problem type URIs

Complete error table

Endpoint-to-error mapping

Authentication and authorization errors

Rate limit errors

Idempotency key errors

Upload lifecycle errors

Permission escalation errors