Object storage API error reference

This page documents common error responses from the Object Storage API, covering both the Swift-native and S3-compatible (SigV4) interfaces. Use this reference when S3 or Swift API calls return unexpected errors.

S3-compatible API errors#

The S3-compatible interface uses AWS-standard error response formats. Errors are returned as XML with an <Error> element containing <Code>, <Message>, <RequestId>, and <Resource>.

Endpoint configuration#

The S3 examples on this page use $RUMBLE_S3_ENDPOINT for the regional Object Storage endpoint. Set it before running them, and replace the region segment to match your region:

export RUMBLE_S3_ENDPOINT=https://object.us-east-1.rumble.cloud

The AWS CLI also reads this value from its native AWS_ENDPOINT_URL variable or the --endpoint-url flag.

Example error response#

<Error>
  <Code>InvalidAccessKeyId</Code>
  <Message>The access key does not exist</Message>
  <RequestId>tx00000abc123def456-00661234-default</RequestId>
  <Resource>/my-bucket/my-key</Resource>
</Error>

Authentication and authorization errors#

Credential type confusion#

The S3-compatible interface requires EC2 credentials, not application credentials. This is the most common cause of authentication failures.

If you are using application credentials with an S3 client, all requests will fail with InvalidAccessKeyId. Switch to EC2 credentials.

Project scope mismatch#

EC2 credentials are scoped to a specific project. If you create credentials in project A but attempt to access a container in project B, the request will fail with AccessDenied.

Diagnosis:

openstack ec2 credentials list -c Access -c Project\ ID

Verify the Project ID matches the project that owns the container.

Resolution: Create credentials in the correct project:

openstack ec2 credentials create --project CORRECT_PROJECT_ID

Signing configuration#

The S3-compatible interface uses AWS SigV4 signing. Common misconfigurations:

AWS CLI configuration example:

aws configure set default.s3.signature_version s3v4
aws configure set default.region us-east-1

Transfer and upload errors#

EntityTooLarge#

HTTP status: 400

Cause: Single-part upload exceeds the maximum object size (5 GB for a single PUT). Files larger than 5 GB require multipart upload.

Resolution:

Configure your client for multipart upload:

aws configure set default.s3.multipart_threshold 64MB
aws configure set default.s3.multipart_chunksize 64MB

Incomplete multipart uploads#

Symptom: Upload was interrupted. The object does not appear in the container, but storage is consumed by uploaded parts.

Diagnosis:

aws s3api list-multipart-uploads --bucket YOUR_CONTAINER --endpoint-url $RUMBLE_S3_ENDPOINT

Resolution:

Abort the incomplete upload:

aws s3api abort-multipart-upload --bucket YOUR_CONTAINER --key YOUR_KEY --upload-id UPLOAD_ID --endpoint-url $RUMBLE_S3_ENDPOINT

Timeout during large transfers#

Cause: Network bandwidth or latency causes individual part uploads to exceed the client's timeout.

Resolution:

• Increase the chunk size to reduce the number of round trips
• Increase client timeout settings
• Use rclone for large or batch transfers (built-in retry and resumable uploads)

Swift-native API errors#

The Swift-native endpoint sits behind the same gateway as the S3-compatible interface. For several conditions the gateway returns S3-style error codes as plain-text bodies (for example NoSuchBucket and NoSuchKey) rather than the upstream Swift response. The entries below give the body string the gateway actually returns, so you can match on it.

401 Unauthorized#

Cause: The X-Auth-Token header carries no valid token: the token expired, was revoked, or never existed. The same response covers an expired token and a bogus or never-issued token.

Response body: AccessDenied (plain text, not Unauthorized).

Resolution: Re-source your credentials and issue a fresh token:

source openrc.sh
openstack token issue

404 from an anonymous request#

Cause: A Swift request sent without an X-Auth-Token header is routed to the S3-compatible gateway, which reads the URL segments as a bucket and key. Anonymous Swift calls do not return 401.

Response body: 404 Not Found with the body NoSuchKey.

Resolution: Send a valid token. If a Swift call returns 404 where you expected an authentication error, confirm you are sending X-Auth-Token before investigating an authorization bug. The Object Storage API reference covers the shared S3 and Swift path behavior.

403 Forbidden#

Cause: The token is valid but does not have the correct role for the requested container or operation.

Resolution: Verify your role assignment and project scope:

openstack role assignment list --user YOUR_USER --project YOUR_PROJECT

404 Not Found#

Cause: The container or object does not exist, or you are using the wrong account prefix.

Response body: The gateway rewrites the Swift 404 to an S3-style code: a missing container returns NoSuchBucket, and a missing object returns NoSuchKey. Both are plain text, so a search for "Container not found" or "Object not found" returns no match.

Resolution:

openstack container list
openstack object list YOUR_CONTAINER

405 Method Not Allowed#

Cause: The HTTP verb is not supported for the target, for example a PATCH on an object.

Response body: MethodNotAllowed

Resolution: Use a supported verb (GET, PUT, POST, DELETE, HEAD, or COPY) for the operation.

409 Conflict#

Cause: The request conflicts with the current state of the resource. The common case is a DELETE on a container that still holds objects.

Response body: There was a conflict when trying to complete your request.

Resolution: Delete the objects first, then the container. To remove a container and its contents in one step:

openstack container delete --recursive YOUR_CONTAINER

412 Precondition Failed#

Cause: A required or conditional header is missing or malformed, for example a COPY request without a Destination header.

Response body: Bad URL

Resolution: Supply the required header. For a COPY, set Destination to /CONTAINER/OBJECT.

400 EntityTooLarge#

HTTP status: 400

Cause: A single object upload exceeds the maximum object size (5 GB for a single PUT). On Quake AI the gateway returns HTTP 400 with the body EntityTooLarge on both the Swift-native and S3-compatible interfaces. A standalone Swift proxy without the Quake AI gateway returns 413 Request Entity Too Large; Quake AI does not emit 413 for this condition.

Response body: EntityTooLarge

Resolution: Use Swift's Static Large Object (SLO) or Dynamic Large Object (DLO) feature for files larger than 5 GB, or use the S3-compatible interface with multipart upload.

429 Too Many Requests#

Cause: Too many API requests in a short time window. Rate limits are enforced at the gateway layer, not by Swift itself.

Resolution: Wait and retry with exponential backoff. Check for a Retry-After header in the response; if present, wait at least that many seconds before retrying.

When to escalate#

Escalate to support when:

• Freshly created EC2 credentials fail with InvalidAccessKeyId immediately after creation
• AccessDenied persists despite correct project scope and credential verification
• Multipart uploads fail consistently even with correct configuration and adequate quota
• Swift-native 401 errors persist after re-sourcing valid credentials and issuing a fresh token

Escalation-ready evidence checklist#

See also#

• Object Storage API reference
• Error response format: S3 XML error structure, request correlation
• API rate limits: quotas vs. rate limits, /limits endpoint, 429 handling
• Retry and resilience patterns: backoff, jitter, and which errors to retry
• Object storage access troubleshooting
• How to create S3 credentials
• Auth token diagnostics