Timeouts de solicitação

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.

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}
  }'

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);

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)

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}
  }'

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,
  },
});

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.
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.

Erro de timeout

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

{
  "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

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');
  }
}

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:

const timeouts = {
  development: 10000, // Fast feedback during dev
  staging: 20000, // Realistic testing
  production: 30000, // Conservative for reliability
};

Timeouts progressivos:

// 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:

{
  "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

// Monitor timeout patterns
const timeoutMetrics = {
  averageResponseTime: 0,
  timeoutRate: 0,
  responseTimesByModel: {},
  optimalTimeout: 0, // 95th percentile + buffer
};

Padrões avançados

Ajuste dinâmico do timeout

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

{
  "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. 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

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.

// 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;
};

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Início rápido

Configuração

Erro de timeout

Valores recomendados

Tratamento de erros

Boas práticas

Integração com fallbacks

Solução de problemas

Padrões avançados

Ajuste dinâmico do timeout

Timeout com streaming

Padrão circuit breaker

Limitações

Monitoramento

​Início rápido

​Configuração

​Erro de timeout

​Valores recomendados

​Tratamento de erros

​Boas práticas

​Integração com fallbacks

​Solução de problemas

​Padrões avançados

​Ajuste dinâmico do timeout

​Timeout com streaming

​Padrão circuit breaker

​Limitações

​Monitoramento

Início rápido

Configuração

Erro de timeout

Valores recomendados

Tratamento de erros

Boas práticas

Integração com fallbacks

Solução de problemas

Padrões avançados

Ajuste dinâmico do timeout

Timeout com streaming

Padrão circuit breaker

Limitações

Monitoramento