> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/honojs/hono/llms.txt
> Use this file to discover all available pages before exploring further.

# timeout

> API reference for the Timeout middleware

## Import

```typescript theme={null}
import { timeout } from 'hono/timeout'
```

## Usage

```typescript theme={null}
const app = new Hono()

app.use(
  '/long-request',
  timeout(5000) // Set timeout to 5 seconds
)

app.get('/long-request', async (c) => {
  await someLongRunningFunction()
  return c.text('Completed within time limit')
})
```

## Parameters

<ParamField path="duration" type="number" required>
  The timeout duration in milliseconds.
</ParamField>

<ParamField path="exception" type="HTTPException | HTTPExceptionFunction">
  The exception to throw when the timeout occurs. Can be:

  * An `HTTPException` object
  * A function that receives the context and returns an `HTTPException`
  * Default: `HTTPException(504, { message: 'Gateway Timeout' })`
</ParamField>

## Signature

```typescript theme={null}
timeout(
  duration: number,
  exception?: HTTPExceptionFunction | HTTPException
): MiddlewareHandler

type HTTPExceptionFunction = (context: Context) => HTTPException
```

## Examples

### Basic usage

```typescript theme={null}
app.use(
  '/long-request',
  timeout(5000) // 5 second timeout
)

app.get('/long-request', async (c) => {
  await someLongRunningFunction()
  return c.text('Completed within time limit')
})
```

### Custom error message

```typescript theme={null}
import { HTTPException } from 'hono/http-exception'

app.use(
  '/api/*',
  timeout(
    10000,
    new HTTPException(408, {
      message: 'Request Timeout: Operation took too long',
    })
  )
)
```

### Dynamic error based on context

```typescript theme={null}
app.use(
  '/api/*',
  timeout(5000, (c) => {
    const path = c.req.path
    return new HTTPException(504, {
      message: `Timeout occurred for ${path}`,
    })
  })
)
```

### Different timeouts for different routes

```typescript theme={null}
const app = new Hono()

// 30 second timeout for uploads
app.use('/upload/*', timeout(30000))

// 5 second timeout for API
app.use('/api/*', timeout(5000))

// 1 second timeout for health checks
app.use('/health', timeout(1000))
```

### With error handler

```typescript theme={null}
app.use('/api/*', timeout(5000))

app.onError((err, c) => {
  if (err instanceof HTTPException) {
    if (err.status === 504) {
      console.error('Timeout occurred:', c.req.path)
      return c.json(
        { error: 'Request timeout', path: c.req.path },
        504
      )
    }
  }
  return c.json({ error: 'Internal Server Error' }, 500)
})
```

### Timeout for specific async operations

```typescript theme={null}
app.get('/data', timeout(10000), async (c) => {
  // This entire handler must complete within 10 seconds
  const data1 = await fetchData1() // 3 seconds
  const data2 = await fetchData2() // 4 seconds
  const data3 = await processData(data1, data2) // 2 seconds
  
  return c.json({ data3 })
})
```

## Behavior

* Races the handler execution against a timeout timer
* Throws the specified HTTPException if timeout is reached
* Default exception is 504 Gateway Timeout
* Cleans up the timer after completion (whether success or timeout)
* Works with async handlers
* Timer is cleared even if handler throws an error
* Can be applied globally or to specific routes
* Multiple timeout middleware can be chained (innermost takes precedence)