Web e Desenvolvimento

Como lidar com timeouts de API, limites de taxa e novas tentativas em PHP

How to Handle API Timeouts, Rate Limits, and Retries in PHP

Aprenda a criar integrações de API PHP confiáveis com timeouts de conexão, tratamento de erros HTTP, retrocesso exponencial, suporte a Retry-After e estratégias seguras de nova tentativa.

Uma integração de API funciona perfeitamente durante o desenvolvimento. Então, um dia, sua tarefa agendada para no meio do caminho. Um serviço remoto responde com HTTP 429, uma conexão atinge o timeout ou um erro HTTP 503 interrompe uma sincronização.

A tentação é tentar novamente a requisição imediatamente.

Mas tentar novamente sem uma estratégia pode piorar o problema. Isso pode sobrecarregar uma API que já está com dificuldades, exceder limites de taxa ou criar acidentalmente pedidos e pagamentos duplicados.

Um cliente de API confiável precisa de mais do que uma chamada curl_exec() bem-sucedida.

Neste tutorial, vamos construir um cliente HTTP prático em PHP que trata timeouts de conexão, erros HTTP, limites de taxa e falhas temporárias. Também explicaremos quando tentar novamente é seguro, quando não é e como diagnosticar problemas em produção.

Os exemplos usam a extensão cURL integrada do PHP, sem Composer ou dependências de terceiros.

1. Entenda os diferentes tipos de falhas de API

Nem toda requisição malsucedida deve ser tratada da mesma forma.

Falha Causa típica Ação recomendada
Timeout de conexão Servidor inacessível ou conexão lenta Tentar novamente com cautela
HTTP 400 Parâmetros de requisição inválidos Corrigir a requisição
HTTP 401 Credenciais inválidas ou expiradas Verificar a autenticação
HTTP 404 Recurso não encontrado Verificar o identificador do recurso
HTTP 429 Limite de taxa da API excedido Respeitar Retry-After
HTTP 500 Erro interno do servidor Tentar novamente seletivamente
HTTP 503 Indisponibilidade temporária do serviço Tentar novamente com atraso
JSON inválido Formato de resposta inesperado Registrar e investigar

Um erro de rede também é diferente de um erro HTTP.

Quando uma API retorna HTTP 500, a requisição HTTP foi concluída e o servidor retornou uma resposta de erro.

Quando o cURL relata uma falha de conexão, sua aplicação pode não ter recebido nenhuma resposta HTTP.

Essa distinção importa ao decidir se deve tentar novamente.

2. Sempre configure timeouts de conexão e de requisição

O cURL do PHP oferece duas configurações particularmente úteis:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT limita a fase de conexão, enquanto CURLOPT_TIMEOUT limita a duração total da transferência. Ambos estão documentados na referência oficial de cURL do PHP.

Sem limites apropriados, um serviço externo lento pode ocupar workers do PHP por muito mais tempo do que o esperado.

Um ponto de partida prático para uma API JSON convencional pode ser cinco segundos para estabelecer a conexão e quinze segundos para a requisição completa.

Esses não são valores universais. Um upload de arquivo ou a geração de um relatório de longa duração pode precisar de uma política de timeout diferente.

Faça sua primeira requisição de API

<?php
declare(strict_types=1);

$url = 'https://api.example.com/products';

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => false,
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo(
    $curl,
    CURLINFO_HTTP_CODE
);

if ($response === false) {
    $error = curl_error($curl);

    curl_close($curl);

    throw new RuntimeException(
        'API request failed: ' . $error
    );
}

curl_close($curl);

echo 'HTTP status: ' . $statusCode;

Isso estabelece uma base útil, mas ainda não trata limites de taxa nem falhas passíveis de nova tentativa.

3. Entenda HTTP 429 e Retry-After

HTTP 429 significa que o cliente enviou requisições demais dentro de um período definido pelo provedor da API.

Algumas APIs impõem limites por minuto, por hora, por chave de API ou por conta.

Um servidor pode responder com:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

O cabeçalho Retry-After informa ao cliente quanto tempo ele deve esperar antes de tentar novamente.

O cabeçalho pode conter um número de segundos ou uma data HTTP.

Por exemplo:

Retry-After: 120

Ou:

Retry-After: Wed, 25 Nov 2026 10:00:00 GMT

Um cliente bem comportado deve respeitar essa instrução em vez de enviar requisições repetidamente.

Se o servidor não fornecer um atraso de nova tentativa, sua aplicação precisa de uma estratégia de fallback.

4. Use backoff exponencial em vez de novas tentativas imediatas

O backoff exponencial aumenta o tempo de espera após falhas sucessivas.

Por exemplo:

Nova tentativa Atraso de exemplo
1 1 segundo
2 2 segundos
3 4 segundos
4 8 segundos

Em vez de tentar novamente a cada segundo, a aplicação espera progressivamente mais.

Adicionar uma pequena variação aleatória, chamada de jitter, ajuda a evitar que muitos clientes tentem novamente simultaneamente.

Aqui está uma função de atraso reutilizável:

<?php
declare(strict_types=1);

function getRetryDelayMs(int $attempt): int
{
    $baseDelay = 1000;
    $maximumDelay = 30000;

    $exponentialDelay = min(
        $maximumDelay,
        $baseDelay * (2 ** ($attempt - 1))
    );

    return random_int(
        0,
        (int)$exponentialDelay
    );
}

Isso usa full jitter: o atraso real é selecionado aleatoriamente entre zero e o limite exponencial.

O atraso aleatório reduz rajadas sincronizadas de novas tentativas, embora não substitua uma instrução Retry-After explícita fornecida pelo servidor.

Illustration of the article's main concept

5. Construa um cliente de API PHP reutilizável

Vamos combinar os conceitos anteriores em uma implementação funcional.

Nosso cliente irá:

  • Definir timeouts de conexão e de duração total da requisição.
  • Retornar o status HTTP e o corpo da resposta.
  • Detectar falhas de transporte.
  • Tentar novamente falhas temporárias selecionadas.
  • Respeitar Retry-After quando presente.
  • Limitar o número de tentativas.
  • Evitar tentar novamente operações não idempotentes automaticamente.
<?php
declare(strict_types=1);

/**
 * Perform an HTTP GET request with bounded retries.
 *
 * Use only with trusted, configured API URLs.
 */
function apiGet(
    string $url,
    int $maxAttempts = 3
): array {
    if ($maxAttempts < 1) {
        throw new InvalidArgumentException(
            'maxAttempts must be at least 1.'
        );
    }

    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        $headers = [];

        $curl = curl_init($url);

        if ($curl === false) {
            throw new RuntimeException(
                'Unable to initialize cURL.'
            );
        }

        curl_setopt_array($curl, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPGET => true,
            CURLOPT_HEADERFUNCTION => static function (
                $curl,
                string $headerLine
            ) use (&$headers): int {
                $length = strlen($headerLine);

                if (str_starts_with(
                    $headerLine,
                    'HTTP/'
                )) {
                    $headers = [];
                }

                $position = strpos(
                    $headerLine,
                    ':'
                );

                if ($position !== false) {
                    $name = strtolower(trim(
                        substr($headerLine, 0, $position)
                    ));

                    $value = trim(
                        substr($headerLine, $position + 1)
                    );

                    $headers[$name] = $value;
                }

                return $length;
            },
        ]);

        $body = curl_exec($curl);
        $curlError = curl_errno($curl);
        $statusCode = (int)curl_getinfo(
            $curl,
            CURLINFO_HTTP_CODE
        );

        curl_close($curl);

        $transportFailure = $body === false;

        $retryableStatus = in_array(
            $statusCode,
            [408, 429, 500, 502, 503, 504],
            true
        );

        if (!$transportFailure && !$retryableStatus) {
            return [
                'status' => $statusCode,
                'body' => $body,
                'headers' => $headers,
                'attempts' => $attempt,
            ];
        }

        if ($attempt === $maxAttempts) {
            throw new RuntimeException(
                'API request failed after '
                . $attempt
                . ' attempts. HTTP '
                . $statusCode
                . ', cURL error '
                . $curlError
            );
        }

        $delayMs = min(
            30000,
            1000 * (2 ** ($attempt - 1))
        );

        $retryAfter = $headers['retry-after'] ?? null;

        if ($retryAfter !== null) {
            if (ctype_digit($retryAfter)) {
                $delayMs = (int)$retryAfter * 1000;
            } else {
                $timestamp = strtotime($retryAfter);

                if ($timestamp !== false) {
                    $delayMs = max(
                        0,
                        $timestamp - time()
                    ) * 1000;
                }
            }
        } else {
            $delayMs = random_int(
                0,
                (int)$delayMs
            );
        }

        // Do not block this worker indefinitely.
        if ($delayMs > 30000) {
            throw new RuntimeException(
                'Retry deferred: waiting time exceeds '
                . 'the synchronous retry budget.'
            );
        }

        usleep((int)$delayMs * 1000);
    }

    throw new RuntimeException(
        'Unexpected retry state.'
    );
}

Como usá-lo

<?php
declare(strict_types=1);

try {
    $result = apiGet(
        'https://api.example.com/products'
    );

    if ($result['status'] !== 200) {
        throw new RuntimeException(
            'Unexpected HTTP status: '
            . $result['status']
        );
    }

    $products = json_decode(
        $result['body'],
        true,
        512,
        JSON_THROW_ON_ERROR
    );

    echo 'API request completed after '
        . $result['attempts']
        . ' attempt(s).';

} catch (Throwable $exception) {
    error_log($exception->getMessage());
}

Esta implementação é intencionalmente limitada a requisições GET para endpoints de API confiáveis.

Ela não tenta novamente automaticamente operações POST, PUT, PATCH ou DELETE, porque essas exigem salvaguardas adicionais.

Ela também retorna respostas HTTP não passíveis de nova tentativa ao chamador, que deve decidir como tratá-las.

Para sistemas de produção, você também deve validar tipos de resposta, impor limites de tamanho de resposta e distinguir erros de transporte passíveis de nova tentativa de falhas permanentes de TLS ou de configuração.

6. Por que tentar novamente requisições POST pode ser perigoso

Imagine uma aplicação de e-commerce enviando esta requisição:

POST /api/orders
Content-Type: application/json

{
  "product_id": 42,
  "quantity": 1
}

A API remota cria o pedido, mas a conexão cai antes que sua aplicação receba a resposta.

Sua aplicação vê um timeout.

O pedido falhou?

Não necessariamente. O pedido pode já existir.

Se sua aplicação tentar novamente imediatamente, ela poderá criar um segundo pedido.

É por isso que um timeout não prova que uma operação falhou no servidor.

Use chaves de idempotência quando houver suporte

Algumas APIs oferecem suporte a chaves de idempotência.

Por exemplo:

Idempotency-Key: order-8f7a2c

Quando a API fornece um mecanismo de idempotência documentado, reutilizar a mesma chave para novas tentativas da mesma operação lógica pode evitar processamento duplicado.

Mas esse comportamento é específico de cada API. Adicionar um cabeçalho Idempotency-Key não torna automaticamente uma API arbitrária idempotente.

Para operações envolvendo pagamentos, pedidos, assinaturas ou modificações em banco de dados, siga a documentação oficial do provedor sobre novas tentativas e idempotência.

Quando não existe mecanismo de idempotência, pode ser necessário consultar o status da operação ou reconciliar os resultados antes de tentá-la novamente.

7. Evite usar sleep dentro de requisições web de longa duração

Technical workflow illustration

Nosso exemplo usa usleep() para tornar o comportamento de nova tentativa fácil de entender.

Isso pode ser aceitável para operações curtas com um orçamento de novas tentativas rigidamente controlado.

No entanto, um site em produção não deve manter workers do PHP ocupados por minutos enquanto espera por uma API externa.

Suponha que uma API responda com:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

Esperar uma hora dentro de uma requisição HTTP seria um design ruim.

Uma solução melhor é adiar a operação.

Por exemplo, armazene um job pendente:

Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC

Um worker agendado pode então processar o job quando ele se tornar elegível.

Essa abordagem é especialmente útil para:

  • Sincronização de catálogo de produtos.
  • Envio de e-mails.
  • Publicação em redes sociais.
  • Processamento de documentos.
  • Atualizações de estoque.
  • Importações grandes via API.

Isso também torna as falhas mais fáceis de monitorar e recuperar.

8. Armazene informações de novas tentativas em um banco de dados

Para uma aplicação baseada em MariaDB, uma tabela de jobs simples poderia ser assim:

CREATE TABLE api_jobs (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    job_type VARCHAR(100) NOT NULL,
    payload_json LONGTEXT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    attempts INT UNSIGNED NOT NULL DEFAULT 0,
    next_attempt_at DATETIME NOT NULL,
    last_error TEXT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    INDEX idx_jobs_ready (
        status,
        next_attempt_at
    )
);

O worker seleciona jobs em que:

SELECT id, job_type, payload_json
FROM api_jobs
WHERE status = 'pending'
AND next_attempt_at <= UTC_TIMESTAMP()
ORDER BY next_attempt_at, id
LIMIT 20;

Esta é apenas a parte de seleção de uma implementação de fila.

Se vários workers podem ser executados simultaneamente, os jobs devem ser reivindicados atomicamente, usando uma estratégia apropriada de transação e bloqueio, para evitar processamento duplicado.

O worker também deve aplicar um número máximo de novas tentativas e mover jobs que falham permanentemente para um estado que exija investigação.

Para uma aplicação pequena, essa abordagem baseada em banco de dados pode ser suficiente sem introduzir Redis ou um broker de mensagens dedicado.

9. Registre falhas sem expor dados sensíveis

Um log útil de API deve responder a quatro perguntas:

  1. Qual operação falhou?
  2. Qual serviço remoto estava envolvido?
  3. Qual foi o status HTTP ou o erro de transporte?
  4. Quando a aplicação tentará novamente?

Por exemplo:

[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z

Evite registrar chaves de API, tokens bearer, cabeçalhos de autorização completos, senhas ou informações pessoais desnecessárias.

Se precisar correlacionar requisições, use um identificador de requisição gerado.

Por exemplo:

$requestId = bin2hex(random_bytes(8));

Você pode incluir esse identificador nos logs da aplicação e, quando houver suporte, enviá-lo à API remota.

10. Teste sua estratégia de novas tentativas antes da produção

Um mecanismo de novas tentativas deve ser testado com cenários de falha previsíveis.

Você não precisa esperar por uma indisponibilidade real da API.

Um endpoint de teste local pode retornar deliberadamente códigos de status específicos.

Por exemplo:

<?php
declare(strict_types=1);

header('Content-Type: application/json');

http_response_code(429);
header('Retry-After: 3');

echo json_encode([
    'error' => 'rate_limit_exceeded',
]);

Execute este endpoint somente em um ambiente de teste local ou protegido.

Em seguida, verifique se seu cliente:

  • Detecta HTTP 429.
  • Lê o cabeçalho Retry-After.
  • Espera antes de tentar novamente.
  • Para após o número configurado de tentativas.
  • Registra a falha sem expor segredos.

Repita com HTTP 503 e um endpoint deliberadamente lento.

Teste também uma resposta HTTP 400 para confirmar que o cliente não tenta novamente erros permanentes de requisição.

Por fim, teste uma operação que possa ter sido concluída com sucesso antes de a conexão falhar. Isso é essencial para integrações de pagamento e pedidos.

11. Uma lista de verificação de produção para integrações de API confiáveis

Antes de implantar uma integração de API, verifique o seguinte:

Verificação Comportamento esperado
Timeout de conexão Definido e testado
Timeout total Definido e testado
HTTP 429 Respeita limites de taxa
HTTP 5xx Tenta novamente seletivamente
HTTP 4xx Sem novas tentativas cegas
Limite de novas tentativas Evita loops infinitos
Atraso entre novas tentativas Backoff com jitter
Operações POST Idempotência ou reconciliação
Períodos longos de espera Adiados para um worker
Logs Úteis, privados, sanitizados
Concorrência de workers Execução duplicada prevenida
Falhas permanentes Visíveis e recuperáveis

Conclusão: APIs confiáveis exigem tratamento controlado de falhas

APIs externas nunca estão perfeitamente disponíveis.

Até mesmo um serviço bem mantido pode passar por sobrecarga temporária, interrupções de rede ou limitação de taxa.

O objetivo não é eliminar todas as falhas. É fazer sua aplicação responder de forma previsível quando falhas acontecerem.

Comece com timeouts sensatos e tratamento explícito de erros HTTP. Adicione novas tentativas limitadas com backoff exponencial, respeite atrasos de nova tentativa fornecidos pelo servidor e evite repetir automaticamente operações que possam criar dados duplicados.

Para integrações mais complexas, mova as novas tentativas para uma fila de jobs persistente em vez de manter requisições web abertas.

Esses princípios se aplicam a quase toda aplicação PHP moderna, seja você criando uma extensão de CMS, sincronizando um catálogo de e-commerce, enviando e-mails transacionais ou integrando um serviço de pagamento.

Um cliente de API confiável é aquele que sabe não apenas como enviar uma requisição, mas também quando tentar novamente, quando esperar e quando parar.

Referências oficiais