Como Lidar com Timeouts da API Perplexity no Código

Quando sua aplicação chama a API Perplexity, uma requisição de rede pode travar ou não ser concluída em um tempo aceitável. Isso faz com que seu código espere indefinidamente, bloqueando interações do usuário ou outros processos críticos. Timeouts de API ocorrem quando o servidor não responde antes que seu cliente desista de esperar. Este artigo explica como configurar timeouts de requisição, capturar erros de timeout e implementar lógica de retry no seu código.

Por que os Timeouts da API Perplexity Ocorrem

Um timeout de API ocorre quando o cliente envia uma requisição mas não recebe uma resposta dentro de um limite de tempo definido. Isso pode acontecer por vários motivos:

• Latência de rede: Conexões lentas de internet ou alta latência entre seu servidor e o endpoint da API Perplexity.
• Sobrecarga do servidor: A Perplexity pode estar com alto tráfego, causando respostas atrasadas.
• Payloads grandes: Enviar prompts muito longos ou solicitar contexto extenso pode aumentar o tempo de processamento.
• Limitação de taxa: Exceder o limite de taxa da API pode fazer com que o servidor atrase ou descarte requisições.

Entender essas causas ajuda a decidir valores de timeout e estratégias de retry apropriados. Um timeout não é uma falha permanente — ele sinaliza que a requisição deve ser tentada novamente ou tratada de outra forma.

Passos para Configurar Timeouts e Tratar Erros

Os passos a seguir mostram como implementar o tratamento de timeout em Python usando a biblioteca requests, que é comumente usada para chamadas à API Perplexity. Adapte a lógica para sua linguagem de programação preferida.

Passo 1: Instalar a Biblioteca Requests

Se você ainda não instalou a biblioteca requests, execute:

pip install requests

Passo 2: Definir um Timeout na Chamada da API

Adicione um parâmetro timeout à sua requisição. O valor é em segundos. Uma escolha comum é 30 segundos para a API Perplexity.

import requests

url = "https://api.perplexity.ai/chat/completions"
headers = {
    "Authorization": "Bearer SUA_CHAVE_API",
    "Content-Type": "application/json"
}
data = {
    "model": "sonar-pro",
    "messages": [{"role": "user", "content": "Explique computação quântica"}]
}

try:
    response = requests.post(url, headers=headers, json=data, timeout=30)
    response.raise_for_status()
    print(response.json())
except requests.exceptions.Timeout:
    print("Requisição excedeu o tempo limite de 30 segundos.")
except requests.exceptions.RequestException as e:
    print(f"Ocorreu um erro: {e}")

O parâmetro timeout instrui o cliente a parar de esperar após 30 segundos. Se o servidor não responder, uma exceção requests.exceptions.Timeout é lançada.

Passo 3: Implementar Retry com Backoff Exponencial

Um único timeout não significa que a requisição sempre falhará. Use um loop de retry que espera mais tempo entre cada tentativa.

import time
import requests

url = "https://api.perplexity.ai/chat/completions"
headers = {
    "Authorization": "Bearer SUA_CHAVE_API",
    "Content-Type": "application/json"
}
data = {
    "model": "sonar-pro",
    "messages": [{"role": "user", "content": "Explique computação quântica"}]
}

max_retries = 3
base_delay = 2  # segundos

for attempt in range(max_retries):
    try:
        response = requests.post(url, headers=headers, json=data, timeout=30)
        response.raise_for_status()
        print("Sucesso:", response.json())
        break
    except requests.exceptions.Timeout:
        wait = base_delay * (2 ** attempt)
        print(f"Timeout na tentativa {attempt + 1}. Tentando novamente em {wait} segundos...")
        time.sleep(wait)
    except requests.exceptions.RequestException as e:
        print(f"Erro não relacionado a timeout: {e}")
        break
else:
    print("Todas as tentativas esgotadas. Requisição falhou.")

Este código tenta novamente até 3 vezes com atrasos de 2, 4 e 8 segundos. Se todas as tentativas falharem, o loop termina com uma mensagem de falha.

Passo 4: Tratar Timeouts em Código Assíncrono

Se você usa asyncio e httpx, defina um timeout no cliente.

import httpx
import asyncio

async def call_perplexity():
    url = "https://api.perplexity.ai/chat/completions"
    headers = {
        "Authorization": "Bearer SUA_CHAVE_API",
        "Content-Type": "application/json"
    }
    data = {
        "model": "sonar-pro",
        "messages": [{"role": "user", "content": "Explique computação quântica"}]
    }
    async with httpx.AsyncClient(timeout=30.0) as client:
        try:
            response = await client.post(url, headers=headers, json=data)
            response.raise_for_status()
            print(response.json())
        except httpx.TimeoutException:
            print("Requisição excedeu o tempo limite.")

asyncio.run(call_perplexity())

O parâmetro timeout em AsyncClient se aplica a toda a requisição. Ajuste o valor conforme seu caso de uso.

Problemas Comuns Após Configurar Timeouts

Valor de Timeout Muito Curto

Se o timeout for muito baixo, até requisições normais podem falhar. Para chamadas à API Perplexity, recomenda-se no mínimo 20 segundos. Aumente para 60 segundos para prompts longos ou contextos grandes.

Loop de Retry Infinito

Sem um número máximo de tentativas, seu código pode tentar indefinidamente. Sempre defina um limite, como 3 ou 5 tentativas. Use backoff exponencial para não sobrecarregar o servidor.

Timeout Não Lançado em Rede Lenta

Algumas bibliotecas têm timeouts separados para as fases de conexão e leitura. Por exemplo, requests permite uma tupla (connect, read). Defina ambos para evitar travamento em rede lenta.

response = requests.post(url, headers=headers, json=data, timeout=(10, 30))

Isso define um timeout de conexão de 10 segundos e um timeout de leitura de 30 segundos.

Limitação de Taxa Causando Timeouts Repetidos

Se você atingir o limite de taxa da Perplexity, o servidor pode atrasar ou descartar requisições. Verifique os cabeçalhos da resposta para informações sobre limite de taxa. Implemente um atraso entre requisições ou use um sistema de fila.

Comparação de Estratégias de Timeout

Estratégia	Descrição	Melhor Caso de Uso
Timeout fixo	Definir um único valor de timeout para todas as requisições	Aplicações simples com tempos de resposta consistentes
Backoff exponencial com retry	Tentar novamente com intervalos de espera crescentes	Lidar com problemas de rede transitórios ou sobrecarga do servidor
Timeouts separados de conexão e leitura	Definir limites diferentes para conexão e transferência de dados	Redes instáveis onde a conexão pode ser bem-sucedida mas a transferência de dados trava
Circuit breaker	Parar de fazer requisições após falhas repetidas por um período	Prevenir falhas em cascata em microsserviços

Agora você pode adicionar tratamento de timeout às suas chamadas da API Perplexity. Comece definindo um timeout de 30 segundos em cada requisição. Em seguida, implemente um loop de retry com backoff exponencial para falhas transitórias. Para sistemas de produção, considere usar o padrão circuit breaker para evitar sobrecarregar a API durante interrupções prolongadas.