Documentation
Examples
SDK Reference
Platform API
Changelogerror_type field. These errors cover timeouts, runner crashes, scheduling failures, and connection problems that occur before or during request processing.
Request errors use a different response format than model validation errors. Model errors return a detail array of typed error objects. Request errors return a flat object with detail as a human-readable string and error_type as a machine-readable category. The same value is also available in the X-Fal-Error-Type response header for programmatic access without parsing the body.
Response Structure
| Property | Description |
|---|---|
detail | A human-readable description of the error. |
error_type | A machine-readable string identifying the error category (see table below). |
X-Fal-Error-Type response header contains the same value as error_type.
Error Type Reference
| Error Type | Description | Typical Status Code |
|---|---|---|
request_timeout | The request exceeded the allowed processing time. | 504 |
startup_timeout | The runner did not start within the allowed time. | 504 |
runner_scheduling_failure | No runner could be allocated to handle the request. | 503 |
runner_connection_timeout | The connection to the runner timed out. | 503 |
runner_disconnected | The runner disconnected unexpectedly during processing. | 503 |
runner_connection_refused | The runner refused the connection. | 503 |
runner_connection_error | A general connection error occurred with the runner. | 503 |
runner_incomplete_response | The runner sent an incomplete response payload. | 502 |
runner_server_error | The runner encountered an internal server error. | 500 |
client_disconnected | The client closed the connection before the response was sent. | 499 |
client_cancelled | The request was cancelled by the client. | 499 |
bad_request | The request was malformed (e.g., invalid timeout header). | 400 |
internal_error | An unexpected internal error occurred. | 500 |
Handling Request Errors
For retry logic: Useerror_type to decide whether to retry. Runner and timeout errors (e.g., runner_connection_timeout, startup_timeout) are typically transient and worth retrying. Client errors (client_disconnected, bad_request) should not be retried. See Retries and Error Handling for how the platform handles retries automatically.
For monitoring: The error_type is also available in queue status responses for failed requests, making it useful for tracking failure patterns in your analytics dashboard.