Error Handling

Error Handling

The SDK uses typed error classes so you can handle different failure scenarios precisely in your application code.

Error Classes

RateLimitError, AuthenticationError, AgentTimeoutError, ToolExecutionError, and ValidationError are the most common. All extend a base AgentError class.

Retries

The client automatically retries on network failures and 5xx errors with exponential backoff. Configure maxRetries and retryDelay in the client options.

Rate Limits

When you hit a rate limit, the client waits for the retry-after header duration before retrying. You can set a maxWait to abort instead of waiting indefinitely.

Error classes

All Queue SDK errors extend QueueError. This makes it easy to catch any Queue-related error in a single catch block while still having access to specific error classes for granular handling.

QueueAuthError

Your API key is missing, invalid, or has been revoked. Check that QUEUE_API_KEY is set correctly and that the key has not been rotated.

QueueRateLimitError

You have exceeded your workspace’s rate limit. The error includes a retryAfter property (in seconds). The SDK retries automatically by default — adjust maxRetries if needed.

QueueTimeoutError

The run exceeded its configured timeout. The partial result up to the point of timeout is available on error.partialResult.

QueueToolError

A tool call failed during execution. Contains the tool name, input, and the underlying error. The agent may have retried the tool before this error was surfaced.

QueueValidationError

The run config failed validation — missing required fields, invalid model name, or unsupported tool. Fix the config and retry.

Automatic retries

The SDK retries automatically on network errors, 429s, and 5xx responses. Default config: 3 retries with exponential backoff starting at 1 second. Override with the retry option on QueueClient:

const client = new QueueClient({ apiKey: process.env.QUEUE_API_KEY, retry: { maxAttempts: 5, initialDelay: 500 }, });

Handling errors gracefully

try { const result = await client.agents.run({ agent: ‘my-agent’, goal: input }); } catch (err) { if (err instanceof QueueRateLimitError) { await sleep(err.retryAfter * 1000); } else if (err instanceof QueueTimeoutError) { console.log(‘Partial result:’, err.partialResult); } else { throw err; } }