fix(api): add configurable request retries

The API block docs described automatic retries, but the block didn't expose any retry controls and requests were executed only once.

This adds tool-level retry support with exponential backoff (including Retry-After support) for timeouts, 429s, and 5xx responses, exposes retry settings in the API block and http_request tool, and updates the docs to match.

Fixes #3225

Author: jayy-77

apps/docs/content/docs/en/blocks/api.mdx

@@ -95,11 +95,17 @@ const apiUrl = `https://api.example.com/users/${userId}/profile`;
 
 ### Request Retries
 
-The API block automatically handles:
-- Network timeouts with exponential backoff
-- Rate limit responses (429 status codes)
-- Server errors (5xx status codes) with retry logic
-- Connection failures with reconnection attempts
+The API block supports **configurable retries** (see the block’s **Advanced** settings):
+
+- **Retries**: Number of retry attempts (additional tries after the first request)
+- **Retry delay (ms)**: Initial delay before retrying (uses exponential backoff)
+- **Max retry delay (ms)**: Maximum delay between retries
+- **Retry non-idempotent methods**: Allow retries for **POST/PATCH** (may create duplicate requests)
+
+Retries are attempted for:
+
+- Network/connection failures and timeouts (with exponential backoff)
+- Rate limits (**429**) and server errors (**5xx**)
 
 ### Response Validation
 

apps/sim/blocks/blocks/api.ts

@@ -89,6 +89,38 @@ Example:
         'Request timeout in milliseconds (default: 300000 = 5 minutes, max: 600000 = 10 minutes)',
       mode: 'advanced',
     },
+    {
+      id: 'retries',
+      title: 'Retries',
+      type: 'short-input',
+      placeholder: '2',
+      description:
+        'Number of retry attempts for timeouts, 429 responses, and 5xx errors (default: 2 for GET/PUT/DELETE/HEAD)',
+      mode: 'advanced',
+    },
+    {
+      id: 'retryDelayMs',
+      title: 'Retry delay (ms)',
+      type: 'short-input',
+      placeholder: '500',
+      description: 'Initial retry delay in milliseconds (exponential backoff)',
+      mode: 'advanced',
+    },
+    {
+      id: 'retryMaxDelayMs',
+      title: 'Max retry delay (ms)',
+      type: 'short-input',
+      placeholder: '30000',
+      description: 'Maximum delay between retries in milliseconds',
+      mode: 'advanced',
+    },
+    {
+      id: 'retryNonIdempotent',
+      title: 'Retry non-idempotent methods',
+      type: 'switch',
+      description: 'Allow retries for POST/PATCH requests (may create duplicate requests)',
+      mode: 'advanced',
+    },
   ],
   tools: {
     access: ['http_request'],
@@ -100,6 +132,16 @@ Example:
     body: { type: 'json', description: 'Request body data' },
     params: { type: 'json', description: 'URL query parameters' },
     timeout: { type: 'number', description: 'Request timeout in milliseconds' },
+    retries: { type: 'number', description: 'Number of retry attempts for retryable failures' },
+    retryDelayMs: { type: 'number', description: 'Initial retry delay in milliseconds' },
+    retryMaxDelayMs: {
+      type: 'number',
+      description: 'Maximum delay between retries in milliseconds',
+    },
+    retryNonIdempotent: {
+      type: 'boolean',
+      description: 'Allow retries for non-idempotent methods like POST/PATCH',
+    },
   },
   outputs: {
     data: { type: 'json', description: 'API response data (JSON, text, or other formats)' },

apps/sim/tools/http/request.ts

@@ -53,6 +53,28 @@ export const requestTool: ToolConfig<RequestParams, RequestResponse> = {
       visibility: 'user-only',
       description: 'Request timeout in milliseconds (default: 300000 = 5 minutes)',
     },
+    retries: {
+      type: 'number',
+      visibility: 'user-only',
+      description:
+        'Number of retry attempts for retryable failures (timeouts, 429, 5xx). Defaults to 2 for idempotent methods (GET/PUT/DELETE/HEAD) and 0 otherwise.',
+    },
+    retryDelayMs: {
+      type: 'number',
+      visibility: 'user-only',
+      description: 'Initial retry delay in milliseconds (default: 500)',
+    },
+    retryMaxDelayMs: {
+      type: 'number',
+      visibility: 'user-only',
+      description: 'Maximum delay between retries in milliseconds (default: 30000)',
+    },
+    retryNonIdempotent: {
+      type: 'boolean',
+      visibility: 'user-only',
+      description:
+        'Allow retries for non-idempotent methods like POST/PATCH (may create duplicate requests).',
+    },
   },
 
   request: {
@@ -119,6 +141,26 @@ export const requestTool: ToolConfig<RequestParams, RequestResponse> = {
 
       return undefined
     }) as (params: RequestParams) => Record<string, any> | string | FormData | undefined,
+
+    retry: {
+      enabled: true,
+      maxRetries: 2,
+      maxRetriesLimit: 10,
+      initialDelayMs: 500,
+      maxDelayMs: 30000,
+      retryOnStatusCodes: [429],
+      retryOnStatusRanges: [{ min: 500, max: 599 }],
+      retryOnTimeout: true,
+      retryOnNetworkError: true,
+      respectRetryAfter: true,
+      retryableMethods: ['GET', 'HEAD', 'PUT', 'DELETE'],
+      paramOverrides: {
+        retries: 'retries',
+        initialDelayMs: 'retryDelayMs',
+        maxDelayMs: 'retryMaxDelayMs',
+        nonIdempotent: 'retryNonIdempotent',
+      },
+    },
   },
 
   transformResponse: async (response: Response) => {

apps/sim/tools/http/types.ts

@@ -9,6 +9,10 @@ export interface RequestParams {
   pathParams?: Record<string, string>
   formData?: Record<string, string | Blob>
   timeout?: number
+  retries?: number
+  retryDelayMs?: number
+  retryMaxDelayMs?: number
+  retryNonIdempotent?: boolean
 }
 
 export interface RequestResponse extends ToolResponse {

apps/sim/tools/index.test.ts

@@ -958,4 +958,148 @@ describe('MCP Tool Execution', () => {
     expect(result.error).toContain('Network error')
     expect(result.timing).toBeDefined()
   })
+
+  describe('Tool request retries', () => {
+    function makeJsonResponse(
+      status: number,
+      body: unknown,
+      extraHeaders?: Record<string, string>
+    ): any {
+      const headers = new Headers({ 'content-type': 'application/json', ...(extraHeaders ?? {}) })
+      return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: status >= 200 && status < 300 ? 'OK' : 'Error',
+        headers,
+        json: () => Promise.resolve(body),
+        text: () => Promise.resolve(typeof body === 'string' ? body : JSON.stringify(body)),
+        arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+        blob: () => Promise.resolve(new Blob()),
+      }
+    }
+
+    it('retries on 5xx responses for http_request', async () => {
+      global.fetch = Object.assign(
+        vi
+          .fn()
+          .mockResolvedValueOnce(makeJsonResponse(500, { error: 'nope' }))
+          .mockResolvedValueOnce(makeJsonResponse(200, { ok: true })),
+        { preconnect: vi.fn() }
+      ) as typeof fetch
+
+      const result = await executeTool('http_request', {
+        url: '/api/test',
+        method: 'GET',
+        retries: 2,
+        retryDelayMs: 0,
+        retryMaxDelayMs: 0,
+      })
+
+      expect(global.fetch).toHaveBeenCalledTimes(2)
+      expect(result.success).toBe(true)
+      expect((result.output as any).status).toBe(200)
+    })
+
+    it('stops retrying after max attempts for http_request', async () => {
+      global.fetch = Object.assign(
+        vi.fn().mockResolvedValue(makeJsonResponse(502, { error: 'bad gateway' })),
+        { preconnect: vi.fn() }
+      ) as typeof fetch
+
+      const result = await executeTool('http_request', {
+        url: '/api/test',
+        method: 'GET',
+        retries: 2,
+        retryDelayMs: 0,
+        retryMaxDelayMs: 0,
+      })
+
+      expect(global.fetch).toHaveBeenCalledTimes(3)
+      expect(result.success).toBe(false)
+    })
+
+    it('does not retry on 4xx responses for http_request', async () => {
+      global.fetch = Object.assign(
+        vi.fn().mockResolvedValue(makeJsonResponse(400, { error: 'bad request' })),
+        { preconnect: vi.fn() }
+      ) as typeof fetch
+
+      const result = await executeTool('http_request', {
+        url: '/api/test',
+        method: 'GET',
+        retries: 5,
+        retryDelayMs: 0,
+        retryMaxDelayMs: 0,
+      })
+
+      expect(global.fetch).toHaveBeenCalledTimes(1)
+      expect(result.success).toBe(false)
+    })
+
+    it('does not retry POST by default (non-idempotent)', async () => {
+      global.fetch = Object.assign(
+        vi
+          .fn()
+          .mockResolvedValueOnce(makeJsonResponse(500, { error: 'nope' }))
+          .mockResolvedValueOnce(makeJsonResponse(200, { ok: true })),
+        { preconnect: vi.fn() }
+      ) as typeof fetch
+
+      const result = await executeTool('http_request', {
+        url: '/api/test',
+        method: 'POST',
+        retries: 2,
+        retryDelayMs: 0,
+        retryMaxDelayMs: 0,
+      })
+
+      expect(global.fetch).toHaveBeenCalledTimes(1)
+      expect(result.success).toBe(false)
+    })
+
+    it('retries POST when retryNonIdempotent is enabled', async () => {
+      global.fetch = Object.assign(
+        vi
+          .fn()
+          .mockResolvedValueOnce(makeJsonResponse(500, { error: 'nope' }))
+          .mockResolvedValueOnce(makeJsonResponse(200, { ok: true })),
+        { preconnect: vi.fn() }
+      ) as typeof fetch
+
+      const result = await executeTool('http_request', {
+        url: '/api/test',
+        method: 'POST',
+        retries: 1,
+        retryNonIdempotent: true,
+        retryDelayMs: 0,
+        retryMaxDelayMs: 0,
+      })
+
+      expect(global.fetch).toHaveBeenCalledTimes(2)
+      expect(result.success).toBe(true)
+      expect((result.output as any).status).toBe(200)
+    })
+
+    it('retries on timeout errors for http_request', async () => {
+      const abortError = Object.assign(new Error('Aborted'), { name: 'AbortError' })
+      global.fetch = Object.assign(
+        vi
+          .fn()
+          .mockRejectedValueOnce(abortError)
+          .mockResolvedValueOnce(makeJsonResponse(200, { ok: true })),
+        { preconnect: vi.fn() }
+      ) as typeof fetch
+
+      const result = await executeTool('http_request', {
+        url: '/api/test',
+        method: 'GET',
+        retries: 1,
+        retryDelayMs: 0,
+        retryMaxDelayMs: 0,
+      })
+
+      expect(global.fetch).toHaveBeenCalledTimes(2)
+      expect(result.success).toBe(true)
+    })
+  })
 })