Errors

Every error response has this body:

{ "error": "human-readable message", "code": "machine_readable_code" }

Branch on code, not on the message or only the status: several codes share a status. Treat a code you do not recognize as internal_error.

Task failures are not errors

A program that exits non-zero, times out, runs out of memory or makes a forbidden syscall does not produce an error response. /execute returns 200, and that task’s result carries the outcome. See how limits show up in results.

The codes below mean Faber did not accept the request, or could not run it.

Codes

Code	Status	Meaning	What to do
invalid_request	400	The body or a parameter is malformed: invalid JSON, a missing or mistyped field, a /file/{id} that is not 64 lowercase hex characters, a multipart upload without a file part	Fix the request. Do not retry
unauthorized	401	Missing or wrong API key	Check the Authorization header. Do not retry
not_found	404	GET or DELETE /file/{id} for a file that is not stored	The file expired, was deleted, or is on another instance
file_not_found	404	A task references a file_id that is not stored. Nothing ran	Upload the file again and retry
cache_disabled	409	DELETE /cache on an instance whose step cache is off	Nothing to clear
payload_too_large	413	The /execute body exceeds EXECUTE_BODY_LIMIT_BYTES, or an upload exceeds UPLOAD_FILE_LIMIT_BYTES	Send large inputs through the file store, or split the work
limits_exceeded	422	More steps than MAX_STEPS_PER_REQUEST, or a parallel step wider than MAX_PARALLEL_TASKS	Split into more requests. GET /info has the limits
profile_not_allowed	422	A task asks for a sandbox_profile outside ALLOWED_SANDBOX_PROFILES	Use an allowed profile (GET /info lists them)
sandbox_setup_failed	500	Faber could not build the sandbox (cgroups, mounts, the jailer)	An operator problem: check the service log for the request ID
internal_error	500	Anything else that went wrong on the server	Retry once; if it persists, report it with the request ID
capacity_exhausted	503	No free task slots for this request; or, for uploads, too many concurrent uploads or the store is full	Retry after Retry-After, or on another instance
shutting_down	503	The instance is draining	Retry on another instance
cancelled	503	The request was cancelled before it finished	Retry
deadline_exceeded	504	The request overran OVERALL_TIMEOUT_MS and was killed by the hard backstop	Usually an overloaded host. Retrying the same request may time out again

Headers

• Retry-After (seconds) may accompany 503. Honor it.
• WWW-Authenticate: Bearer accompanies 401.
• x-request-id is on every response, errors included. The service logs the same ID; quote it when reporting a problem.

Retry policy

A good default for clients, and what the SDKs implement:

1. Retry 503 and connection failures, waiting Retry-After seconds if given, otherwise with exponential backoff and jitter, a few times at most.
2. Retry file_not_found once after re-uploading the referenced files.
3. Never retry other 4xx codes.
4. Treat 500 and 504 as worth one retry at most, and log the request ID.