Tavily Error Handlers

The Tavily plugin includes built-in error handlers for common Tavily API error scenarios.

Built-in Error Handlers

Rate Limit Errors

Triggers: HTTP 429 status

Behavior:

• Maximum retries: 5
• Respects Retry-After header

Example:

// Corsair handles rate limits automatically
await corsair.tavily.api.search({
    query: "your search query", 
});

Authentication Errors

Triggers: HTTP 401 status, invalid API key

Behavior:

• Maximum retries: 0 (no retries)
• Fails immediately

How to Fix:

1. Verify your Tavily API key is valid
2. Check the key has not expired or been revoked

Network Errors

Triggers: Connection errors, timeouts

Behavior:

• Maximum retries: 3
• Uses exponential backoff

Default Handler

Triggers: Any unmatched error

Behavior:

• Maximum retries: 0 (no retries)

Custom Error Handlers

tavily({
    errorHandlers: {
        SEARCH_TIMEOUT: {
            match: (error) => {
                return error.message.includes("timeout"); 
            },
            handler: async (error, context) => {
                return {
                    maxRetries: 2,
                    headersRetryAfterMs: 2000, 
                };
            },
        },
    },
})

For comprehensive error handling strategies, patterns, and best practices, see the Error Handling concepts page.