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

# Timeouts de solicitação

> Defina uma duração máxima para solicitações de LLM com o parâmetro timeout no AI Gateway para evitar chamadas travadas e acionar modelos de fallback automáticos.

**Casos de uso**

* Impedir que modelos lentos bloqueiem indefinidamente solicitações voltadas ao usuário.
* Definir limites diferentes para cargas de trabalho interativas (curtas) e em lote (longas).
* Acionar a lógica de fallback quando um provedor excede um tempo de espera aceitável.
* Garantir SLAs de tempo de resposta em recursos sensíveis à latência.

***

## Início rápido

Defina a duração máxima da solicitação para evitar solicitações travadas.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize AI trends for 2024",
    "timeout": {"call_timeout": 30000}
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Summarize AI trends for 2024",
  timeout: {
    call_timeout: 30000,
  },
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Summarize AI trends for 2024",
    extra_body={"timeout": {"call_timeout": 30000}},
)

print(response.output_text)
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [{ "role": "user", "content": "Summarize AI trends for 2024" }],
    "timeout": {"call_timeout": 30000}
  }'
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Summarize AI trends for 2024" }],
  timeout: {
    call_timeout: 30000,
  },
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Summarize AI trends for 2024"}],
    extra_body={"timeout": {"call_timeout": 30000}},
)
```

## Configuração

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `call_timeout` | number | Não | Tempo máximo da chamada ao modelo, em milissegundos. O padrão é `720000` (12 minutos) quando `timeout` é omitido. |

**O timeout se aplica a:**

* Tempo de geração do modelo em chamadas sem streaming. A chamada inteira precisa terminar dentro de `call_timeout`.
* Tempo até o primeiro token em chamadas com streaming. Consulte [Timeout com streaming](#timeout-with-streaming).
* Cada tentativa de retry e de fallback. Cada tentativa recebe o próprio `call_timeout`, exceto na Responses API com streaming, em que as tentativas compartilham o prazo da solicitação.

`call_timeout` limita apenas a chamada ao modelo. Ele não limita Guardrails nem Evaluators: cada referência de Guardrail na solicitação tem o próprio `timeout`, com padrão igual ao tempo limite do Evaluator ou, se ele não tiver um, 60 segundos, e configurável até 10 minutos. Consulte [Timeout de Guardrail](/docs/pt-BR/ai-gateway/configuration/guardrails.md#timeout).

### Erro de timeout

Quando `call_timeout` é atingido, o gateway cancela a tentativa e responde com HTTP `408`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "message": "Request timed out. The operation took longer than the configured timeout.",
    "type": "timeout_error",
    "param": null,
    "code": "timeout_error"
  }
}
```

`408` faz parte dos códigos padrão de retry e dos códigos padrão de fallback, então quem faz a chamada só recebe esse erro depois que os retries e fallbacks se esgotam.

## Valores recomendados

| Caso de uso | Timeout (ms) | Motivo |
| - | - | - |
| **Aplicações de chat** | `15000` (15s) | Expectativa do usuário quanto às respostas |
| **Recursos em tempo real** | `5000` (5s) | Retorno imediato necessário |
| **Processamento em lote** | `60000` (60s) | Tarefas de análise complexas |
| **Respostas em streaming** | `30000` (30s) | Tempo de geração mais longo |
| **Desenvolvimento/testes** | `10000` (10s) | Ciclos de iteração rápidos |

## Tratamento de erros

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

try {
  const response = await client.responses.create({
    model: "openai/gpt-5.6-sol",
    input: "Explain quantum computing",
    timeout: { call_timeout: 15000 },
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionTimeoutError) {
    console.log('Request timed out - try increasing timeout or using faster model');
  }
}
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

try {
  const response = await client.chat.completions.create({
    model: "openai/gpt-5.6-sol",
    messages: [{ role: "user", content: "Explain quantum computing" }],
    timeout: { call_timeout: 15000 }
  });
} catch (error) {
  if (error instanceof OpenAI.APIConnectionTimeoutError) {
    console.log('Request timed out - try increasing timeout or using faster model');
    // Implement fallback behavior
  }
}
```

## Boas práticas

**Escolha do timeout:**

* Defina com base nos requisitos de experiência do usuário.
* Considere a complexidade do modelo e o tamanho do prompt.
* Leve em conta a latência da rede (adicione uma margem de 2 a 5 s).
* Teste com prompts e dados realistas.

**Timeouts específicos por ambiente:**

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const timeouts = {
  development: 10000, // Fast feedback during dev
  staging: 20000, // Realistic testing
  production: 30000, // Conservative for reliability
};
```

**Timeouts progressivos:**

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Start with short timeout, increase for retries
const attempts = [
  { timeout: 10000, model: "fast-model" },
  { timeout: 20000, model: "standard-model" },
  { timeout: 30000, model: "comprehensive-model" },
];
```

## Integração com fallbacks

Os timeouts funcionam perfeitamente com fallbacks:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "timeout": { "call_timeout": 15000 },
  "fallbacks": [
    { "model": "openai/gpt-5.6-sol" },
    { "model": "openai/gpt-5.4-mini" }
  ]
}
```

**Tempo total possível, em chat completions e chamadas sem streaming:** `timeout × (1 + retry_count) × (1 + fallback_count)`

* Modelo principal mais 2 fallbacks com timeout de 15 s e os 2 retries padrão: 15 s × 3 tentativas × 3 modelos, até 135 s mais os intervalos de backoff entre retries.
* A solicitação inteira também é limitada por um prazo interno: 12 minutos para solicitações sem streaming ou que executam um Agent, e 30 minutos para as demais solicitações de modelo com streaming. Com `timeout` omitido, o padrão de 12 minutos já é igual ao prazo sem streaming.

## Solução de problemas

**Timeouts frequentes**

* Aumente o valor do timeout.
* Use modelos mais rápidos (gpt-5.4-mini em vez de gpt-5.6-sol).
* Reduza a complexidade/o tamanho do prompt.
* Verifique o status do provedor para identificar lentidão.

**Problemas de experiência do usuário**

* Defina o timeout com base nas expectativas do usuário.
* Exiba estados de carregamento para operações mais longas.
* Implemente aprimoramento progressivo.
* Considere o processamento assíncrono para tarefas longas.

**Otimização de desempenho**

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Monitor timeout patterns
const timeoutMetrics = {
  averageResponseTime: 0,
  timeoutRate: 0,
  responseTimesByModel: {},
  optimalTimeout: 0, // 95th percentile + buffer
};
```

## Padrões avançados

### Ajuste dinâmico do timeout

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const getDynamicTimeout = (promptLength, modelComplexity) => {
  const baseTimeout = 10000;
  const promptFactor = Math.min(promptLength / 1000, 3); // Max 3x for long prompts
  const modelFactor = modelComplexity === "simple" ? 1 : 2;

  return baseTimeout * promptFactor * modelFactor;
};
```

### Timeout com streaming

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "stream": true,
  "timeout": {
    "call_timeout": 30000
  }
}
```

Com `stream: true`, `call_timeout` limita a espera pelo primeiro token, não a duração total do stream. O cronômetro para quando o primeiro chunk chega, então um stream que continua produzindo tokens pode durar mais que `call_timeout`.

Depois do primeiro token, o gateway cancela o stream somente quando o provedor fica em silêncio por mais tempo que o timeout de inatividade do stream, que é de 12 minutos.

Se o timeout for atingido antes do primeiro token, `/v3/router/chat/completions` retorna HTTP `408` com o corpo `timeout_error` de [Erro de timeout](#timeout-error). Em `/v3/router/responses`, um stream já aberto termina com um evento `response.failed` cujo `error.code` é `timeout_error`.

Na Responses API com streaming, as tentativas compartilham o prazo geral da solicitação, então o orçamento até o primeiro token de um retry é limitado ao orçamento restante da solicitação dividido pelas tentativas restantes.

### Padrão circuit breaker

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
class CircuitBreaker {
  timeout: number;
  failureCount: number;
  failureThreshold: number;
  state: "CLOSED" | "OPEN" | "HALF_OPEN";
  openedAt: number | null;

  constructor(timeout: number, failureThreshold = 5) {
    this.timeout = timeout;
    this.failureCount = 0;
    this.failureThreshold = failureThreshold;
    this.state = "CLOSED";
    this.openedAt = null;
  }

  async call<T>(requestFn: () => Promise<T>): Promise<T> {
    if (this.state === "OPEN") {
      if (this.openedAt !== null && Date.now() - this.openedAt < this.timeout) {
        throw new Error("Circuit breaker is OPEN");
      }
      this.state = "HALF_OPEN";
    }

    try {
      const result = await requestFn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  onSuccess() {
    this.failureCount = 0;
    this.state = "CLOSED";
    this.openedAt = null;
  }

  onFailure() {
    this.failureCount += 1;
    if (this.failureCount >= this.failureThreshold) {
      this.state = "OPEN";
      this.openedAt = Date.now();
    }
  }
}
```

## Limitações

* **Timeout fixo**: `call_timeout` não se adapta ao tamanho do prompt nem ao modelo.
* **Multiplicação por fallback**: cada tentativa de fallback recebe o mesmo `call_timeout`, então a latência no pior caso se multiplica pelo número de tentativas.
* **Variações entre provedores**: provedores diferentes têm tempos de resposta de referência diferentes.
* **Streaming**: `call_timeout` limita apenas o primeiro token; o timeout de inatividade do stream limita o restante.

## Monitoramento

Principais métricas a acompanhar:

* **Taxa de timeout**: % de solicitações que atingem o timeout.
* **Tempo médio de resposta**: desempenho de referência.
* **Percentil 95**: para definir timeouts ideais.
* **Impacto do timeout**: degradação da experiência do usuário.
* **Desempenho do modelo**: tempos de resposta por modelo.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Example monitoring
const metrics = {
  totalRequests: 0,
  timeouts: 0,
  responseTimes: [] as number[],
  recommendedTimeout: 0,
};

const calculatePercentile = (arr: number[], p: number): number => {
  const sorted = [...arr].sort((a, b) => a - b);
  return sorted[Math.floor((p / 100) * sorted.length)] ?? 0;
};

const monitorTimeouts = (responseTime: number, wasTimeout: boolean) => {
  metrics.totalRequests++;
  if (wasTimeout) {
    metrics.timeouts++;
  } else {
    metrics.responseTimes.push(responseTime);
  }

  // Calculate optimal timeout (95th percentile + 5s buffer)
  const p95 = calculatePercentile(metrics.responseTimes, 95);
  metrics.recommendedTimeout = p95 + 5000;
};
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.