Error Codes

Complete reference of 22 error codes returned by the Vault Service API.

Error Response Format

{
  "statusCode": 404,
  "message": "Asset not found",
  "error": "ERR_VAULT_NOT_FOUND",
  "timestamp": "2026-02-21T12:00:00.000Z",
  "path": "/vault/v1/assets/abc-123",
  "method": "GET",
  "request_id": "uuid",
  "tenantId": "uuid"
}

400 Bad Request

Errors caused by invalid client input.

Code	HTTP	Name	Resolution
ERR_VAULT_INVALID_INPUT	400	Validation Failed	Refer to the API Reference for required fields and types.
ERR_VAULT_INVALID_MIME_TYPE	400	Unsupported File Type	Use allowed MIME types: image/, video/, audio/*, application/pdf. Allowed types vary by tier.
ERR_VAULT_INVALID_FILE_SIZE	400	File Too Large	Reduce file size or upgrade plan to increase per-file size limit.
ERR_VAULT_FOLDER_NOT_EMPTY	400	Folder Not Empty	Move or delete all contents within the folder first, or use ?force=true (admin only).
ERR_VAULT_CIRCULAR_REFERENCE	400	Circular Reference	Choose a different parent folder. A folder cannot be moved into itself or descendants.
ERR_VAULT_INVALID_VERSION	400	Invalid Version	Check version history via GET /vault/v1/assets/:id/versions first.

401 Unauthorized

Errors caused by missing or invalid authentication.

Code	HTTP	Name	Resolution
ERR_VAULT_UNAUTHORIZED	401	Missing/Invalid JWT	Include a valid Bearer token from auth-svc. Ensure the token has not been revoked.
ERR_VAULT_TOKEN_EXPIRED	401	Token Expired	Refresh token via auth-svc refresh endpoint. Do not reuse expired tokens.

403 Forbidden

Errors caused by insufficient permissions or exceeded quotas.

Code	HTTP	Name	Resolution
ERR_VAULT_FORBIDDEN	403	Insufficient Permissions	Check the required role for the endpoint. Contact your tenant admin for elevated access.
ERR_VAULT_LEGAL_HOLD	403	Asset Under Legal Hold	Release legal hold first via DELETE /vault/v1/assets/:id/legal-hold (admin only).
ERR_VAULT_QUOTA_EXCEEDED	403	Quota Exceeded	Upgrade tier or delete files. Check usage via GET /vault/v1/quota.
ERR_VAULT_PRIVATE_ASSET	403	Private Asset	Change visibility to public via PATCH /vault/v1/assets/:id, then retry.

404 Not Found

Errors caused by referencing non-existent resources.

Code	HTTP	Name	Resolution
ERR_VAULT_NOT_FOUND	404	Not Found	Verify ID exists and belongs to your tenant. Assets are isolated via RLS.
ERR_VAULT_PARENT_NOT_FOUND	404	Parent Folder Not Found	Verify parent folder ID. List available folders via GET /vault/v1/folders.

409 Conflict

Errors caused by conflicting state or business rule violations.

Code	HTTP	Name	Resolution
ERR_VAULT_DUPLICATE	409	Duplicate Asset	Use the existing asset (ID returned in error details) or force upload.
ERR_VAULT_FOLDER_EXISTS	409	Folder Exists	Choose a different folder name or move the existing folder.

500 Internal Server Error

Server-side failures. Report if persistent.

Code	HTTP	Name	Resolution
ERR_VAULT_UPLOAD_FAILED	500	Upload Failed	Check S3 bucket permissions. Verify IAM role has s3:PutObject. Retry after a brief delay.
ERR_VAULT_TRANSFORM_FAILED	500	Transform Failed	Check input format and options. Verify source asset is not corrupted. Check CloudWatch logs.
ERR_VAULT_DB_ERROR	500	Database Error	Check DB connectivity and RLS config. Review CloudWatch logs with request_id.
ERR_VAULT_KAFKA_ERROR	500	Kafka Error	Check MSK Serverless cluster health. Review CloudWatch logs with request_id.

503 Service Unavailable

Downstream service unavailability.

Code	HTTP	Name	Resolution
ERR_VAULT_DB_UNAVAILABLE	503	DB Unavailable	Check Aurora PostgreSQL status in AWS Console. Verify VPC security groups.
ERR_VAULT_CACHE_UNAVAILABLE	503	Cache Unavailable	Check ElastiCache status. Verify Redis endpoint is reachable from Lambda security group.