swift — Errors

Errors — swift — branch stable/2026.2

Branch stable/2026.2 @ a1bdaeba21bd — repository https://opendev.org/openstack/swift — analysed on 2026-10-29

Swift returns HTTP statuses, not error codes: there is no JSON error body and no business code. What a client sees is decided in three places: the validation helpers and middlewares (4xx before any backend call), the storage servers (statuses of each replica) and the proxy's quorum logic, which turns N backend statuses into one client status. Exceptions are internal: they are converted to statuses inside each server and never cross the wire as such. The S3 API (s3api) is the exception: it returns S3 XML errors with codes.

1. Error body

Clients parse statuses, not texts. python-swiftclient raises ClientException(http_status, http_reason, http_response_content) and retries 5xx, 408, 499 and (by default) 498/429; it re-authenticates once on 401 (python-swiftclient:swiftclient/client.py:1773). Glance's store maps 404 → NotFound, 409 → Duplicate, 413 → StorageFull (glance_store:glance_store/_drivers/swift/store.py:1129). See 07 § 4.

2. How the proxy chooses the status: quorum

For writes and for HEAD/GET of accounts and containers the proxy collects one status per backend node and calls best_response (swift/proxy/controllers/base.py:2225):

1. Statuses are grouped by class 2xx, 3xx, 4xx (swift/proxy/controllers/base.py:2272). The first class, in that order, that reaches the quorum wins; within it the highest status is returned with its reason and body.
2. Quorum: floor(n/2)+1 for account/container rings and replicated policies (swift/common/utils/__init__.py:2550, swift/common/storage_policy.py:438); ec_ndata + min_parity_fragments_needed() for EC PUTs (swift/common/storage_policy.py:637).
3. If no class reaches the quorum, the proxy answers 503 and logs <type> returning 503 for <statuses> (swift/proxy/controllers/base.py:2267).
4. overrides lets some statuses count as others: for DELETE, a 404 is turned into 204 when a quorum is otherwise impossible; for container PUT, 202 and 201 mix.

Consequences that clients observe (and a rewrite must reproduce):

• 5xx never wins a quorum by itself: 3 nodes answering 507, 507, 201 give 503, not 507.
• A 404 on GET object is returned only when every primary (and the handoffs tried) answered 404; one node holding a tombstone newer than another node's data makes the proxy return 404 because the newest timestamp wins (X-Backend-Timestamp).
• A POST with mixed 404 and 202 where a replica proved the object exists gives 503 (swift/proxy/controllers/obj.py:961).
• A node that keeps failing is error-limited: after error_suppression_limit (10) errors within error_suppression_interval (60 s) it is skipped (swift/proxy/server.py:229, swift/common/error_limiter.py:33). A 507 marks a node error-limited at once (swift/proxy/controllers/obj.py:783).

3. Client-facing statuses

4. Storage-server statuses (internal wire)

These are what a Go storage node must return to Python proxies and daemons (and what a Go proxy must interpret):

5. Exception catalogue (internal)

Exceptions are defined in swift/common/exceptions.py and converted by the server that catches them. The ones that change a status or a behaviour:

The inventory (_inventory/inventory_stable-2026.2.json) lists all 196 exception classes found, including the 60 s3api error classes and the CLI ones.

6. S3 API errors

s3api converts Swift statuses into S3 errors (swift/common/middleware/s3api/s3response.py): 404 on a container → NoSuchBucket, on an object → NoSuchKey; 409 on container DELETE → BucketNotEmpty; 401/403 → AccessDenied, SignatureDoesNotMatch, InvalidAccessKeyId, RequestTimeTooSkewed; 413 → EntityTooLarge; 400 from SLO for small parts → EntityTooSmall; unknown → InternalError. Each class sets its _status and _msg; extra elements (BucketName, Key…) come from constructor kwargs. The functional run recorded the combinations actually returned: _rewrite/observed-errors_stable-2026.2.md.

7. Errors outside the request path

Source: reverse-spec-swift/02-errors_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.