Web y desarrollo

Cómo manejar los tiempos de espera de la API, límites de tasa y reintentos en PHP

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

Aprende a construir integraciones API de PHP confiables con tiempos de espera de conexión, manejo de errores HTTP, retroceso exponencial, soporte Retry-After y estrategias de reintentos seguras.

Cómo manejar tiempos de espera, límites de tasa y reintentos en API con PHP

Una integración API funciona perfectamente durante el desarrollo. Luego, un día, tu tarea programada se detiene a mitad de camino. Un servicio remoto responde con HTTP 429, una conexión agota el tiempo de espera, o un error HTTP 503 interrumpe una sincronización.

La tentación es reintentar la solicitud inmediatamente.

Pero reintentar sin una estrategia puede empeorar el problema. Puede sobrecargar una API que ya está luchando, exceder los límites de tasa, o crear accidentalmente órdenes y pagos duplicados.

Un cliente API confiable necesita más que una llamada curl_exec() exitosa.

En este tutorial, construiremos un cliente HTTP práctico en PHP que maneje tiempos de espera de conexión, errores HTTP, límites de tasa y fallos temporales. También explicaremos cuándo es seguro reintentar, cuándo no lo es, y cómo diagnosticar problemas en producción.

Los ejemplos usan la extensión cURL integrada de PHP, sin Composer ni dependencias de terceros.

1. Entender los diferentes tipos de fallos en API

No cada solicitud fallida debe manejarse de la misma manera.

Fallo Causa típica Acción recomendada
Tiempo de espera de conexión Servidor inalcanzable o conexión lenta Reintentar con cautela
HTTP 400 Parámetros de solicitud inválidos Corregir la solicitud
HTTP 401 Credenciales inválidas o expiradas Verificar autenticación
HTTP 404 Recurso no encontrado Verificar identificador del recurso
HTTP 429 Límite de tasa de API excedido Respetar Retry-After
HTTP 500 Error interno del servidor Reintentar selectivamente
HTTP 503 Servicio no disponible temporalmente Reintentar con demora
JSON inválido Formato de respuesta inesperado Registrar e investigar

Un error de red también es diferente de un error HTTP.

Cuando una API devuelve HTTP 500, la solicitud HTTP se completó y el servidor devolvió una respuesta de error.

Cuando cURL reporta un fallo de conexión, tu aplicación podría no haber recibido ninguna respuesta HTTP en absoluto.

Esta distinción importa al decidir si reintentar.

2. Siempre configurar tiempos de espera de conexión y solicitud

PHP cURL proporciona dos configuraciones particularmente útiles:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT limita la fase de conexión, mientras que CURLOPT_TIMEOUT limita la duración total de la transferencia. Ambos están documentados en la referencia oficial de cURL de PHP.

Sin límites apropiados, un servicio externo lento puede ocupar trabajadores PHP por mucho más tiempo del esperado.

Un punto de partida práctico para una API JSON convencional podría ser cinco segundos para el establecimiento de conexión y quince segundos para la solicitud completa.

Estos no son valores universales. Una carga de archivo o generación de informe de larga duración puede necesitar una política de tiempo de espera diferente.

Realiza tu primera solicitud 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;

Esto establece una base útil, pero aún no maneja límites de tasa ni fallos reintentables.

3. Entender HTTP 429 y Retry-After

HTTP 429 significa que el cliente ha enviado demasiadas solicitudes dentro de un período definido por el proveedor de la API.

Algunas APIs imponen límites por minuto, por hora, por clave API, o por cuenta.

Un servidor puede responder con:

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

El encabezado Retry-After indica al cliente cuánto tiempo debe esperar antes de intentar de nuevo.

El encabezado puede contener un número de segundos o una fecha HTTP.

Por ejemplo:

Retry-After: 120

O:

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

Un cliente bien comportado debe respetar esta instrucción en lugar de enviar solicitudes repetidamente.

Si el servidor no proporciona una demora de reintento, tu aplicación necesita una estrategia de respaldo.

4. Usar retroceso exponencial en lugar de reintentos inmediatos

El retroceso exponencial aumenta el tiempo de espera después de fallos sucesivos.

Por ejemplo:

Reintento Demora de ejemplo
1 1 segundo
2 2 segundos
3 4 segundos
4 8 segundos

En lugar de reintentar cada segundo, la aplicación espera progresivamente más tiempo.

Agregar una pequeña variación aleatoria, llamada jitter, ayuda a prevenir que muchos clientes reintenten simultáneamente.

Aquí hay una función de demora reutilizable:

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

Esto usa jitter completo: la demora real se selecciona aleatoriamente entre cero y el tope exponencial.

La demora aleatoria reduce ráfagas de reintento sincronizadas, aunque no reemplaza una instrucción explícita Retry-After proporcionada por el servidor.

Illustration of the article's main concept

5. Construir un cliente API PHP reutilizable

Combinemos los conceptos anteriores en una implementación funcional.

Nuestro cliente:

  • Establecerá tiempos de espera de conexión y solicitud general.
  • Devolverá el estado HTTP y el cuerpo de la respuesta.
  • Detectará fallos de transporte.
  • Reintentará fallos temporales seleccionados.
  • Respetará Retry-After cuando esté presente.
  • Limitará el número de intentos.
  • Evitará reintentar operaciones no idempotentes automáticamente.
<?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.'
    );
}

Cómo usarlo

<?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 implementación está intencionalmente limitada a solicitudes GET contra endpoints API confiables.

No reintenta automáticamente operaciones POST, PUT, PATCH o DELETE, porque esas requieren salvaguardas adicionales.

También devuelve respuestas HTTP no reintentables al llamador, que debe decidir cómo manejarlas.

Para sistemas de producción, además deberías validar tipos de respuesta, imponer límites de tamaño de respuesta, y distinguir errores de transporte reintentables de fallos TLS o de configuración permanentes.

6. Por qué reintentar solicitudes POST puede ser peligroso

Imagina una aplicación de comercio electrónico enviando esta solicitud:

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

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

La API remota crea la orden, pero la conexión se corta antes de que tu aplicación reciba la respuesta.

Tu aplicación ve un tiempo de espera.

¿Falló la orden?

No necesariamente. La orden puede ya existir.

Si tu aplicación reintenta inmediatamente, podría crear una segunda orden.

Por esto un tiempo de espera no prueba que una operación falló en el servidor.

Usar claves de idempotencia cuando sean compatibles

Algunas APIs soportan claves de idempotencia.

Por ejemplo:

Idempotency-Key: order-8f7a2c

Cuando la API proporciona un mecanismo de idempotencia documentado, reutilizar la misma clave para reintentos de la misma operación lógica puede prevenir procesamiento duplicado.

Pero este comportamiento es específico de la API. Agregar un encabezado Idempotency-Key no hace automáticamente idempotente una API arbitraria.

Para operaciones que involucran pagos, órdenes, suscripciones o modificaciones de base de datos, sigue la documentación oficial de reintentos e idempotencia del proveedor.

Cuando no existe mecanismo de idempotencia, puede que necesites consultar el estado de la operación o reconciliar resultados antes de intentarlo de nuevo.

7. Evitar dormir dentro de solicitudes web de larga duración

Technical workflow illustration

Nuestro ejemplo usa usleep() para hacer el comportamiento de reintento fácil de entender.

Eso puede ser aceptable para operaciones cortas con un presupuesto de reintento estrictamente controlado.

Sin embargo, un sitio web de producción no debería mantener trabajadores PHP ocupados por minutos mientras espera una API externa.

Supongamos que una API responde con:

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

Esperar una hora dentro de una solicitud HTTP sería un mal diseño.

Una mejor solución es diferir la operación.

Por ejemplo, almacena un trabajo pendiente:

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

Un trabajador programado puede luego procesar el trabajo cuando sea elegible.

Este enfoque es especialmente útil para:

  • Sincronización de catálogo de productos.
  • Entrega de correos electrónicos.
  • Publicación en redes sociales.
  • Procesamiento de documentos.
  • Actualizaciones de inventario.
  • Importaciones masivas de API.

También hace que los fallos sean más fáciles de monitorear y recuperar.

8. Almacenar información de reintento en una base de datos

Para una aplicación con MariaDB, una tabla de trabajos simple podría verse así:

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

El trabajador selecciona trabajos donde:

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;

Esto es solo la parte de selección de una implementación de cola.

Si varios trabajadores pueden ejecutarse simultáneamente, los trabajos deben reclamarse atómicamente, usando una estrategia de transacción y bloqueo apropiada, para prevenir procesamiento duplicado.

El trabajador también debería aplicar un conteo máximo de reintentos y mover trabajos que fallan permanentemente a un estado que requiera investigación.

Para una aplicación pequeña, este enfoque basado en base de datos puede ser suficiente sin introducir Redis o un broker de mensajes dedicado.

9. Registrar fallos sin exponer datos sensibles

Un registro API útil debe responder cuatro preguntas:

  1. ¿Qué operación falló?
  2. ¿Qué servicio remoto estuvo involucrado?
  3. ¿Cuál fue el estado HTTP o error de transporte?
  4. ¿Cuándo reintentará la aplicación?

Por ejemplo:

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

Evita registrar claves API, tokens bearer, encabezados de autorización completos, contraseñas, o información personal innecesaria.

Si necesitas correlacionar solicitudes, usa un identificador de solicitud generado.

Por ejemplo:

$requestId = bin2hex(random_bytes(8));

Puedes incluir este identificador en los registros de la aplicación y, cuando sea compatible, enviarlo a la API remota.

10. Probar tu estrategia de reintento antes de producción

Un mecanismo de reintento debe probarse contra escenarios de fallo predecibles.

No necesitas esperar una caída real de API.

Un endpoint de prueba local puede devolver deliberadamente códigos de estado específicos.

Por ejemplo:

<?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',
]);

Ejecuta este endpoint solo en un entorno de prueba local o protegido.

Luego verifica que tu cliente:

  • Detecta HTTP 429.
  • Lee el encabezado Retry-After.
  • Espera antes de reintentar.
  • Se detiene después del número configurado de intentos.
  • Registra el fallo sin exponer secretos.

Repite con HTTP 503 y un endpoint deliberadamente lento.

También prueba una respuesta HTTP 400 para confirmar que el cliente no reintenta errores de solicitud permanentes.

Finalmente, prueba una operación que pudo haber tenido éxito antes de que fallara la conexión. Esto es esencial para integraciones de pagos y órdenes.

11. Lista de verificación para integraciones API confiables en producción

Antes de desplegar una integración API, verifica lo siguiente:

Verificación Comportamiento esperado
Tiempo de espera de conexión Definido y probado
Tiempo de espera general Definido y probado
HTTP 429 Respeta límites de tasa
HTTP 5xx Reintenta selectivamente
HTTP 4xx No reintentos ciegos
Límite de reintentos Previene bucles infinitos
Demora de reintento Retroceso con jitter
Operaciones POST Idempotencia o reconciliación
Períodos de espera largos Diferidos a un trabajador
Registros Útiles, privados, sanitizados
Concurrencia de trabajadores Ejecución duplicada prevenida
Fallos permanentes Visibles y recuperables

Conclusión: APIs confiables requieren manejo controlado de fallos

Las APIs externas nunca están perfectamente disponibles.

Incluso un servicio bien mantenido puede experimentar sobrecarga temporal, interrupciones de red, o limitación de tasa.

El objetivo no es eliminar cada fallo. Es hacer que tu aplicación responda predeciblemente cuando ocurren fallos.

Comienza con tiempos de espera sensatos y manejo explícito de errores HTTP. Agrega reintentos acotados con retroceso exponencial, respeta demoras de reintento proporcionadas por el servidor, y evita repetir automáticamente operaciones que podrían crear datos duplicados.

Para integraciones más complejas, mueve los reintentos a una cola de trabajos persistente en lugar de mantener solicitudes web abiertas.

Estos principios se aplican a casi toda aplicación PHP moderna, ya sea que estés construyendo una extensión CMS, sincronizando un catálogo de comercio electrónico, enviando correos transaccionales, o integrando un servicio de pagos.

Un cliente API confiable es uno que sabe no solo cómo enviar una solicitud, sino también cuándo reintentar, cuándo esperar, y cuándo detenerse.

Referencias oficiales