Configuration des Timeouts API

Les timeouts sont un élément crucial mais souvent négligé de la configuration des API. Un timeout définit combien de temps votre application attend une réponse avant d'abandonner et de considérer la requête comme échouée. Sans timeout approprié, une requête peut bloquer indéfiniment, paralysant progressivement toute votre application.

Le choix du timeout est un équilibre délicat. Trop court : des requêtes légitimes mais lentes échouent inutilement. Trop long : votre application devient vulnérable aux services lents ou indisponibles, accumulant des connexions bloquées et des threads en attente.

Ce guide vous aidera à comprendre les différents types de timeouts, à choisir des valeurs appropriées selon le contexte, et à implémenter des stratégies de gestion d'erreur robustes pour créer des intégrations API résilientes.

Types de Timeout

Plusieurs types de timeout interviennent à différentes étapes de la requête :

• Connection timeout : temps maximum pour établir la connexion TCP. Typiquement 5-10 secondes. Un échec indique un serveur inaccessible ou un problème réseau.
• Read timeout (socket timeout) : temps maximum pour recevoir les données une fois la connexion établie. Dépend de la complexité de l'opération côté serveur.
• Total timeout : temps maximum pour l'ensemble de la requête (connexion + traitement + réponse). Utile comme garde-fou global.
• Idle timeout : temps maximum d'inactivité sur une connexion keepalive avant fermeture. Gère les connexions persistantes.

Valeurs Recommandées par Cas d'Usage

Les timeouts optimaux varient selon le type d'opération :

• Healthcheck / Status : connection: 3s, read: 5s. Un healthcheck doit répondre rapidement, sinon il indique déjà un problème.
• Lecture simple (GET) : connection: 5s, read: 15s. La plupart des lectures devraient répondre en quelques secondes.
• Écriture (POST/PUT) : connection: 5s, read: 30s. Les écritures peuvent impliquer des validations et des transactions plus longues.
• Opérations lourdes (exports, rapports) : connection: 10s, read: 300s+. Préférez les opérations asynchrones avec polling ou webhooks.

Implémentation des Timeouts

Voici comment configurer les timeouts dans différents contextes :

// PHP avec cURL
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CONNECTTIMEOUT => 5,    // Connection timeout: 5s
    CURLOPT_TIMEOUT => 30,          // Total timeout: 30s
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if (curl_errno($ch)) {
    $error = curl_error($ch);
    // Gérer l'erreur de timeout
}
curl_close($ch);

// JavaScript avec fetch et AbortController
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s timeout

try {
    const response = await fetch(url, {
        signal: controller.signal
    });
    clearTimeout(timeoutId);
    return await response.json();
} catch (error) {
    if (error.name === 'AbortError') {
        console.error('Request timeout');
    }
    throw error;
}

Ces exemples montrent la configuration de timeouts en PHP (cURL) et JavaScript (fetch). Adaptez les valeurs selon votre cas d'usage spécifique.

Bonnes Pratiques de Gestion des Timeouts

Au-delà de la configuration, ces pratiques améliorent la résilience :

• Retry avec backoff : après un timeout, réessayez avec un délai croissant (1s, 2s, 4s). Évite de surcharger un service en difficulté.
• Circuit breaker : après plusieurs échecs consécutifs, arrêtez temporairement les appels vers le service défaillant.
• Fallback gracieux : prévoyez une réponse de secours (cache, valeur par défaut) quand le service ne répond pas à temps.
• Logging détaillé : loguez les timeouts avec contexte (URL, durée, type d'opération) pour faciliter le diagnostic.

Questions Fréquentes - Timeouts API

Des Timeouts Bien Configurés, c'est la Résilience

Les timeouts sont votre première ligne de défense contre les services défaillants. Sans eux, une seule API lente peut paralyser toute votre application. Avec des timeouts bien configurés et une gestion d'erreur appropriée, votre système reste réactif même face à des dépendances problématiques.

MoniTao utilise des timeouts optimisés pour la surveillance et vous alerte quand vos services ne répondent pas dans les délais attendus. Combiné avec une bonne configuration côté applicatif, vous construisez une infrastructure véritablement résiliente.

Prêt à dormir sur vos deux oreilles ?

Commencez gratuitement, sans carte bancaire.

Créer mon compte Voir les tarifs