Errors and retries

Before a response starts

Use the HTTP status to distinguish failed requests. Gateway errors can include JSON. Disk routes may return plain text or operation-specific JSON.

Status	Typical cause
400	Invalid name/path/query, unsupported shell syntax, oversized exec source or invalid KV cursor.
401	Missing, repeated or incorrect Authorization header.
404	Missing disk, file, parent directory or stored script.
413	KV key/value/batch or JSON body exceeds its size limit.
415	KV request lacks a supported JSON content type.
422	KV JSON has an invalid shape or unsupported field/operation.
500	Storage, I/O or data corruption failure.

Exact failures depend on the route. Endpoint reference pages list their relevant cases.

After streaming starts

Exec returns HTTP 200 before execution completes. Read the final exit record. A command error can produce stderr and status 1; an execution failure such as a JS exception can produce stderr and status 2. A missing final record means the execution response is incomplete.

Directory and KV scan streams can fail after their headers. Their body then terminates with an error. Check the HTTP client’s body-read result. These streams have no execution exit record.

Retry a mutation

A disconnect, timeout or storage error after publication can leave the write applied. The server has no idempotency-key protocol and does not automatically roll back prior operations in a failed JS or shell script.

Inspect current state before retrying work that must run once. Repeating a complete PUT of the same file bytes or KV value expresses the same replacement, but other concurrent writers may have changed the target. A KV batch groups put/delete publication; it does not add conditional updates or conflict detection.

For critical preceding writes, use the persistence barrier. Storage failures can delay flush and eviction. A timeout alone does not establish whether a barrier completed.