Errors and troubleshooting

Use the quickstart client. Replace uppercase IDs with your resource IDs.

Request errors

Inspect response.status and response.error for execution failures. Catch AgentRequestError for transport or request failures.

import { agent } from "./client.ts";
import { AgentRequestError } from "@fal-ai/client";

try {
  await agent.responses.retrieve("RESPONSE_ID");
} catch (error) {
  if (!(error instanceof AgentRequestError))
    throw error;
  console.error(
    error.status,
    error.message,
    error.responseId,
  );
}

Error field	Meaning
`message`	Request failure description.
`status`	Optional HTTP status.
`responseId`	Accepted or observed response identity when known.
`idempotencyKey`	Mutation key when available.
`lastResponse`	Last observed snapshot when available.
`cause`	Underlying transport, abort, timeout, or protocol error.

Error context is optional. An absent HTTP status can indicate a local timeout, abort, or network failure.

HTTP status	Action
`400`	Correct the request or cursor using the returned error message.
`401` / `403`	Check your credentials and account access.
`404`	Check the resource ID and access permissions.
`409`	Retrieve current state. Resolve the revision, cursor, or idempotency conflict before retrying.
`410`	The retained response is no longer available.
`422`	Correct the input using the returned error message.

Local and protocol errors

Invalid options or IDs can throw TypeError before a request starts. Correct the argument instead of retrying it. AgentProtocolError indicates an invalid snapshot, response identity, or stream envelope. It can appear inside an AgentRequestError.cause chain. Retrieve the response by its saved ID. AgentEvent describes the transport envelope. agent.stream yields response views, not raw event objects.

Choose a recovery action

Situation	What happened	Next action
`run()` resolved with `failed`	The request was accepted, but execution failed.	Read `response.error` and any available artifacts before deciding on a new task.
A helper returned `waiting_for_input`	The response needs an answer or approval.	Read `pending_inputs`, answer, then resume observation of the same ID.
Create or answer lost its acknowledgement	The server might have accepted the command.	Retry the exact body with the same idempotency key.
A stream disconnected	Local observation stopped. Execution can continue.	Reconnect with `responses.stream(id)` or retrieve the response.
A local timeout expired	The helper reached its observation deadline.	Retrieve the response. Call `responses.cancel` to stop execution.
A plan or final-selection write returned `409`	The expected revision or sequence no longer matches.	Read the latest state and apply your changes to that version.
A history page returned `409`	The history snapshot changed.	Discard accumulated pages and restart pagination.
A resource write lost its acknowledgement	The resource could have changed.	Read it back before retrying. A run retry can create another paid attempt.

Rate limits and service failures

For 429, reduce concurrent requests and avoid immediate retry loops. For 5xx or network failures, allow time between attempts. When retrying a submission, preserve its original idempotency key and body. Correct validation or permission errors before retrying.

Capture useful diagnostics

Record the SDK version, method, HTTP status, error message, and response ID when available. For execution failures, record the response status and phase. Remove credentials and private prompt content before sharing logs.

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

Errors and troubleshooting

Request errors

Local and protocol errors

Choose a recovery action

Rate limits and service failures

Capture useful diagnostics

​Request errors

​Local and protocol errors

​Choose a recovery action

​Rate limits and service failures

​Capture useful diagnostics

Request errors

Local and protocol errors

Choose a recovery action

Rate limits and service failures

Capture useful diagnostics