Gateway Error Codes & Custom Headers

Standardized S3 REST XML error payloads, HTTP status codes, and custom Aarkam headers.

Last updated: Sep 23, 2026

Aarkam.Gateway returns standard S3 REST error payloads formatted as XML to ensure 100% interoperability with third-party S3 SDKs, tools, and backup agents.

1. Standard Error Response Format

When an operation fails, the gateway returns an HTTP status code accompanied by an XML error body:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>AccessDenied</Code>
    <Message>Access Denied: Object is locked under WORM COMPLIANCE mode.</Message>
    <Resource>/financial-vault/ledger-2026.enc</Resource>
    <RequestId>req-984028472918471928</RequestId>
</Error>

2. Error Code Mapping Matrix

S3 Error Code	HTTP Status	Root Cause & Resolution
`AccessDenied`	`403 Forbidden`	Invalid SigV4 signature, expired credentials, or attempting to mutate a WORM-locked object.
`NoSuchBucket`	`404 Not Found`	The specified bucket does not exist within the tenant namespace.
`NoSuchKey`	`404 Not Found`	The specified object key does not exist.
`BucketAlreadyExists`	`409 Conflict`	Bucket name collision across tenant namespaces.
`BucketNotEmpty`	`409 Conflict`	Cannot delete bucket containing active objects or version tombstones.
`EntityTooLarge`	`400 Bad Request`	Single `PutObject` payload exceeds maximum size (5GB limit; use Multipart Upload).
`InvalidPart`	`400 Bad Request`	Part byte length or ETag mismatch during multipart upload assembly.
`SignatureDoesNotMatch`	`403 Forbidden`	Calculated HMAC-SHA256 signature does not match client `Authorization` header.
`SlowDown`	`503 Service Unavailable`	Request rate exceeds tenant IOPS quota threshold; client should apply exponential backoff.
`InternalError`	`500 Server Error`	Transient daemon failure or storage node timeout; automatically retried by SDKs.

3. Supported Custom Request & Response Headers

Header Name	Type	Description
`x-amz-server-side-encryption`	Request/Response	Cryptographic algorithm: `AES256` or `aws:kms`.
`x-amz-server-side-encryption-aws-kms-key-id`	Request	Customer HSM / KMS ARN used for envelope key wrapping.
`x-amz-object-lock-mode`	Request/Response	WORM governance mode: `COMPLIANCE` or `GOVERNANCE`.
`x-amz-object-lock-retain-until-date`	Request/Response	ISO-8601 UTC timestamp determining the expiration of immutable retention.
`x-amz-object-lock-legal-hold`	Request/Response	Legal hold status: `ON` or `OFF`. Overrides standard retention expiration.
`x-aarkam-erasure-profile`	Response	Active Cauchy Reed-Solomon profile (e.g., `ahmodi-8-3`).
`x-aarkam-sovereign-region`	Response	Certified geographic residency zone (e.g., `sa-central-1`).