Errors

Every Rayfold error has a code from a fixed list, the same in every API, so retries, alerts and status codes work the same way everywhere. Errors an operation declares in the schema, such as OutOfStock, use the code domain and carry their own type and data.

When a whole request is refused over HTTP, the answer is an RFC 9457 problem document whose type links to one of these pages.

Type	HTTP	Retry?	Meaning
invalid_argument	400	no	The request does not match the schema, so nothing ran.
failed_precondition	400	no	The request is valid, but the data is not in the state the operation needs.
out_of_range	400	no	The operation went past the end of what exists, such as reading beyond the last item.
unauthenticated	401	no	The server could not tell who is calling.
permission_denied	403	no	The server knows who is calling, and they are not allowed to do this.
not_found	404	no	What the request names does not exist, or the caller is not allowed to know that it does.
already_exists	409	no	The command would create something that is already there.
aborted	409	yes	The operation was stopped by a conflict with another one running at the same time.
resource_exhausted	429	no	The request is over a limit the server enforces.
payload_too_large	413	no	The request body is bigger than the server accepts. Nothing was read past the limit and nothing ran.
unsupported_media_type	415	no	The request body is in a format this endpoint does not read.
canceled	499	no	The caller stopped the request before it finished.
unimplemented	501	no	This server does not support the operation or feature the request uses.
unavailable	503	yes	The server or something it depends on is down for the moment.
deadline_exceeded	504	yes	The request's deadline passed before the server finished.
domain	422	no	An error the schema declares for this operation, such as `OutOfStock`. It arrives with a `type` and its data.
internal	500	no	Something went wrong inside the server. The details stay in its logs.
unknown	500	no	An error came from somewhere that did not say what kind it was.
data_loss	500	no	Data was lost or corrupted, and the server could not recover it.

Commands can always be sent again with the same idempotency key: if the first attempt went through, the server answers with its original result instead of running the command twice.