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.
Model Errors
Validation errors from model inputs (images, video, audio)
Retries
How fal automatically retries failed requests