Request Error Types

When a request fails due to infrastructure-level issues rather than model validation, the platform returns a structured error response with a machine-readable error_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).

{
  "detail": "Request timed out",
  "error_type": "request_timeout"
}

The 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

Concurrency Limit Errors

The synchronous API returns 429 when you reach your account’s concurrent request limit or a per-endpoint limit. This response does not have an error_type field. It has a type field and a data object:

{
  "detail": "Reached concurrent requests limit of 10",
  "type": "concurrent_requests_limit",
  "data": {"limit": 10, "notify": true}
}

The data.limit field is the limit that applies. The data.notify field is true for the account limit and false for a per-endpoint limit. The response also has the headers X-Fal-Needs-Retry: 1 and X-Fal-Needs-Retry-Type: concurrent_requests_limit. Retry the request after one of your requests completes. The queue API does not return this error. The queue keeps the request until capacity is available.

Handling Request Errors

For retry logic: Use error_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

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

Request Error Types

Response Structure

Error Type Reference

Concurrency Limit Errors

Handling Request Errors

Model Errors

Retries

​Response Structure

​Error Type Reference

​Concurrency Limit Errors

​Handling Request Errors

Model Errors

Retries

Response Structure

Error Type Reference

Concurrency Limit Errors

Handling Request Errors