Appendix A. Error Responses
The status codes below recur across nearly every endpoint in this guide with the same meaning each time; endpoint sections list the codes their spec declares, so the codes in this table apply to every endpoint whether or not they are listed there.
| Status | Meaning | Details |
|---|---|---|
202 |
Accepted. | The request was accepted and the desired state recorded, but the change has not happened yet. Poll the resource, such as an S3 gateway instance’s observed field, to see when it takes effect. |
207 |
Multi-Status. | Returned by calls that act on several targets at once, such as the S3 instance calls that fan out across nodes, when some succeeded and some did not. The body lists a result for each target. |
400 |
Bad request. | The request was well-formed JSON but rejected by request-specific validation, for example an out-of-range field or a value that conflicts with another field. detail is a human-readable explanation. |
401 |
Unauthorized. | The Authorization header is missing, the token is invalid or expired, or (for POST /auth/login) the credentials were wrong. Login failures and unknown users answer with the same body, to avoid user and tenant enumeration. |
403 |
Forbidden. | The caller is authenticated but lacks the permission the endpoint requires, or a request-specific rule blocks the call for a caller in this state (for example, a delegated tenant-switch session cannot issue an API token). |
404 |
Not found. | No resource exists at the given identifier, or (for endpoints that avoid leaking existence, such as another user’s API token) it belongs to someone else and answers identically to not existing at all. |
409 |
Conflict. | The request is valid but conflicts with the current state of the system, for example creating a volume whose pathname already exists or deleting a resource something else still depends on. |
422 |
Validation error. | The request body or parameters failed schema validation before any business logic ran. detail is a list of ValidationError objects, each naming the offending field (loc), the problem (msg), and the failure type (type). See HTTPValidationError in Appendix B. |
500 |
Internal server error. | An unexpected failure on the server side. The request may or may not have taken effect; check the resource’s current state before retrying a non-idempotent call. |
503 |
Service unavailable. | A backend dependency (typically the storage backend) was unreachable, or something the request needs is not in place, such as a running S3 gateway instance for a bucket call. The request changed nothing. A 503 for an unreachable dependency is worth retrying once it recovers; a 503 for a missing prerequisite will not clear on retry until the prerequisite is met. |
504 |
Gateway timeout. | The operation took too long to answer. It may still have completed, since a volume or bucket can appear afterward, so list the resources before retrying a create. |