Limites de débit de l'API Zendesk : Un guide complet pour les développeurs pour 2026

Si vous créez des intégrations avec Zendesk, rencontrer une erreur 429 Too Many Requests (Trop de requêtes) à 2 heures du matin n'est pas amusant. Comprendre les limites de débit de l'API Zendesk avant de commencer à coder vous évite des séances de débogage frénétiques et des parties prenantes en colère qui se demandent pourquoi leur synchronisation de tickets a cessé de fonctionner.

Ce guide détaille tout ce que vous devez savoir sur les limites de débit de l'API Zendesk. Nous aborderons les limites à plusieurs niveaux par plan, comment surveiller votre utilisation en temps réel et les stratégies pratiques pour gérer les erreurs de limite de débit avec élégance. Que vous synchronisiez des données de tickets, que vous construisiez un tableau de bord personnalisé ou que vous automatisiez des flux de travail, vous apprendrez à créer des intégrations qui restent dans les limites tout en offrant des performances fiables.

Pour les équipes qui préfèrent ne pas du tout gérer les limites de débit, il existe une autre voie. eesel AI se connecte directement à Zendesk et gère automatiquement la limitation du débit. Nous explorerons les deux approches afin que vous puissiez choisir celle qui convient le mieux à votre équipe.

Comprendre les limites de débit à plusieurs niveaux de Zendesk

Zendesk applique différentes limites de débit en fonction de votre type de plan et des points de terminaison API spécifiques que vous utilisez. Décomposons ce que vous devez savoir.

Limites de débit par niveau de plan

Les limites de débit de l'API Support et Centre d'aide varient considérablement en fonction de votre plan Zendesk :

Source : Documentation sur les limites de débit de Zendesk

L'extension High Volume API augmente votre limite à 2500 requêtes par minute. Elle est disponible sur les plans Zendesk Suite Growth et supérieurs, et sur les plans Zendesk Support Professional et supérieurs. Vous aurez besoin d'un minimum de 10 postes d'agent pour acheter cette extension. Les plans Enterprise Plus incluent cette extension par défaut.

Limites spécifiques aux points de terminaison

Certains points de terminaison ont leurs propres limites de débit qui remplacent les limites de l'ensemble du compte :

Source : Documentation sur les limites de débit de Zendesk

Le point de terminaison Incremental Export (Exportation incrémentale) est particulièrement important si vous synchronisez de grands ensembles de données. Vous ne pouvez effectuer que 10 requêtes par minute vers ces points de terminaison, bien que ce nombre passe à 30 requêtes par minute si vous avez l'extension High Volume API.

Considérations relatives à l'API du Centre d'aide

L'API du Centre d'aide utilise les mêmes limites de débit que l'API Support. Cependant, les requêtes à l'API du Centre d'aide ne sont pas comptabilisées dans votre limite de débit de l'API Support, et vice versa. Cela signifie que vous pouvez effectuer 700 requêtes à l'API Support et 700 requêtes supplémentaires à l'API du Centre d'aide simultanément sur un plan Enterprise.

Surveillance des requêtes par minute de limite de débit de l'API Zendesk dans votre code

Zendesk fournit des en-têtes de réponse qui vous permettent de surveiller l'état de votre limite de débit en temps réel. Ceci est essentiel pour créer des intégrations qui peuvent adapter dynamiquement leur taux de requêtes.

Comprendre les en-têtes de réponse

Chaque réponse API de Zendesk inclut des en-têtes qui vous indiquent l'état actuel de votre limite de débit :

• X-Rate-Limit ou ratelimit-limit : La limite de débit actuelle de votre compte (par exemple, 700)
• X-Rate-Limit-Remaining ou ratelimit-remaining : Nombre de requêtes restantes dans la minute actuelle
• ratelimit-reset : Horodatage Unix indiquant le moment où la fenêtre de limite de débit actuelle est réinitialisée
• zendesk-ratelimit-tickets-index : Informations de limite supplémentaires pour les points de terminaison de la liste des tickets

Pour les points de terminaison de la liste de l'API Ticketing comme List Tickets (Liste des tickets) ou Search Users (Rechercher des utilisateurs), vous obtenez des en-têtes supplémentaires :

x-rate-limit: 700
ratelimit-limit: 700
x-rate-limit-remaining: 699
ratelimit-remaining: 699
ratelimit-reset: 41
zendesk-ratelimit-tickets-index: total=100; remaining=99; resets=41

Source : Meilleures pratiques de Zendesk pour éviter la limitation du débit

Lecture des en-têtes en Python

Voici comment extraire et utiliser les en-têtes de limite de débit en Python :

import requests
import time

def call_zendesk_api():
    url = "https://subdomain.zendesk.com/api/v2/tickets"
    headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
    response = requests.get(url, headers=headers)
    should_continue = handle_rate_limits(response)
    if should_continue:
        # Process the API response
        pass

def handle_rate_limits(response):
    account_limit = response.headers.get("ratelimit-remaining")
    endpoint_limit = response.headers.get("Zendesk-RateLimit-Endpoint")
    account_limit_reset = response.headers.get("ratelimit-reset")

    if account_limit:
        account_remaining = int(account_limit)
        if account_remaining > 0:
            if endpoint_limit:
                endpoint_remaining = int(endpoint_limit.split(";")[1].split("=")[1])
                if endpoint_remaining > 0:
                    return True
                else:
                    endpoint_reset = int(endpoint_limit.split(";")[2].split("=")[1])
                    handle_limit_exceeded(endpoint_reset)
            else:
                return True
        else:
            handle_limit_exceeded(account_limit_reset)
    return False

def handle_limit_exceeded(reset_time):
    wait_time = int(reset_time) - int(time.time()) + 1
    print(f"Rate limit exceeded. Waiting {wait_time} seconds...")
    time.sleep(wait_time)

Source : Documentation des meilleures pratiques de Zendesk

Lecture des en-têtes en JavaScript

Voici la même logique en JavaScript avec async/await :

const axios = require('axios');

async function callZendeskAPI() {
    const url = "https://subdomain.zendesk.com/api/v2/tickets";
    const headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"};
    try {
        const response = await axios.get(url, { headers });
        const shouldContinue = handleRateLimits(response);
        if (shouldContinue) {
            // Process the API response
        }
    } catch (error) {
        console.error(error);
    }
}

function handleRateLimits(response) {
    const accountLimit = response.headers["ratelimit-remaining"];
    const endpointLimit = response.headers["Zendesk-RateLimit-endpoint"];
    const accountLimitReset = response.headers["ratelimit-reset"];

    if (accountLimit) {
        const accountRemaining = parseInt(accountLimit);
        if (accountRemaining > 0) {
            if (endpointLimit) {
                const endpointRemaining = parseInt(endpointLimit.split(";")[1].split("=")[1]);
                if (endpointRemaining > 0) {
                    return true;
                } else {
                    const endpointReset = parseInt(endpointLimit.split(";")[2].split("=")[1]);
                    handleLimitExceeded(endpointReset);
                }
            } else {
                return true;
            }
        } else {
            handleLimitExceeded(accountLimitReset);
        }
    }
    return false;
}

async function handleLimitExceeded(resetTime) {
    const waitTime = (resetTime || 60) - Math.floor(Date.now() / 1000) + 1;
    console.log(`Rate limit exceeded. Waiting ${waitTime} seconds...`);
    await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
}

Source : Documentation des meilleures pratiques de Zendesk

Gestion des erreurs 429 Too Many Requests (Trop de requêtes)

Lorsque vous dépassez les requêtes par minute de limite de débit de l'API Zendesk, l'API renvoie un code d'état 429. La façon dont vous gérez cette réponse détermine si votre intégration échoue avec élégance ou se casse complètement. Pour plus de contexte sur la création d'intégrations robustes, consultez notre guide sur les meilleurs chatbots d'IA pour Zendesk.

Que signifient les erreurs 429

Une réponse 429 Too Many Requests (Trop de requêtes) indique que vous avez atteint la limite de débit. La réponse inclut un en-tête Retry-After qui vous indique le nombre de secondes à attendre avant de réessayer :

HTTP/1.1 429
Status: 429
Retry-After: 93

Dans cet exemple, vous devrez attendre 93 secondes avant de faire une autre requête. Ignorer cet en-tête et continuer à faire des requêtes peut entraîner des erreurs null qui rendront le débogage difficile.

Source : Documentation des meilleures pratiques de Zendesk

Mise en œuvre d'un repli exponentiel

Pour les intégrations de production, mettez en œuvre un repli exponentiel pour gérer les limites de débit avec élégance :

import time
import random

def make_request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response
        elif response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            # Exponential backoff with jitter
            wait_time = retry_after * (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Waiting {wait_time:.1f} seconds...")
            time.sleep(wait_time)
        else:
            response.raise_for_status()

    raise Exception("Max retries exceeded")

L'approche de repli exponentiel augmente le temps d'attente entre les nouvelles tentatives, ce qui réduit le risque de submerger le serveur tout en améliorant la probabilité de requêtes réussies.

Meilleures pratiques pour la gestion des erreurs

Voici les pratiques clés pour gérer les limites de débit en production :

• N'ignorez jamais les erreurs 429. Continuer à faire des requêtes après avoir atteint la limite peut faire échouer votre intégration avec des erreurs null inutiles.
• Analysez toujours l'en-tête Retry-After. Cela vous indique exactement combien de temps attendre.
• Mettez en œuvre des modèles de disjoncteur pour les applications à volume élevé. Si vous atteignez systématiquement les limites de débit, suspendez temporairement les requêtes plutôt que de réessayer immédiatement.
• Enregistrez les événements de limite de débit. Suivez quand et pourquoi vous atteignez les limites pour identifier les possibilités d'optimisation.
• Concevez pour une dégradation progressive. Votre application doit continuer à fonctionner même lorsque les requêtes API sont retardées.

Surveillance de l'utilisation de l'API dans Zendesk

Au-delà de la surveillance des en-têtes dans votre code, Zendesk fournit des outils pour suivre votre utilisation de l'API au fil du temps.

Utilisation du tableau de bord du Centre d'administration

Vous pouvez consulter votre utilisation de l'API dans le Centre d'administration Zendesk :

1. Allez dans Centre d'administration > Compte > Utilisation > API
2. Consultez le résumé de 7 jours montrant votre utilisation par rapport à votre limite de débit
3. Vérifiez le pourcentage d'erreurs 429 au cours des sept derniers jours
4. Voyez combien de fois vous avez approché votre limite (90-99 % de la capacité)

Le tableau de bord affiche les requêtes API au fil du temps avec des tableaux décomposant le nombre total de requêtes par appelant et par point de terminaison. Le contenu est actualisé quotidiennement, bien qu'il puisse prendre jusqu'à 72 heures pour que l'utilisation actuelle apparaisse.

Source : Gestion de l'utilisation de l'API dans votre compte Zendesk

Remarque : Le tableau de bord d'utilisation de l'API n'est pas disponible pour les comptes utilisant plus de 2500 requêtes par minute ou les comptes autonomes qui n'incluent pas Support.

Notifications d'utilisation de l'API

Zendesk fournit des notifications lorsque vous approchez de votre limite de débit :

• Avertissements de quasi-violation : Alertes lorsque les appels API mesurent entre 90 et 99 % de la limite de votre plan
• Suivi des erreurs 429 : Surveillez le pourcentage de requêtes renvoyant des erreurs de limite de débit
• Résumés quotidiens : Suivez les tendances au cours des 7 derniers jours

Une surveillance régulière vous aide à identifier les modèles et à planifier les augmentations de capacité avant que l'atteinte des limites n'affecte vos opérations.

Optimisation de votre intégration API

Une conception d'intégration intelligente réduit votre utilisation de l'API sans sacrifier les fonctionnalités. Voici des stratégies éprouvées pour rester dans les requêtes par minute de limite de débit de l'API Zendesk. Si vous recherchez une compréhension plus approfondie des outils de support basés sur l'IA, consultez notre revue de Zendesk AI.

Traitement par lots des requêtes

Au lieu de faire des appels API individuels pour chaque ticket, utilisez les points de terminaison de lot :

• points de terminaison show_many : Récupérez plusieurs tickets, utilisateurs ou organisations en une seule requête
• Chargement latéral : Utilisez le paramètre include pour récupérer les données associées (comme les commentaires de tickets) en un seul appel
• Mises à jour en bloc : Mettez à jour plusieurs tickets avec une seule requête lorsque cela est possible

Le traitement par lots peut réduire votre volume d'appels API de 50 à 90 % selon votre cas d'utilisation.

Mise en œuvre de la mise en cache

Mettez en cache les données qui ne changent pas fréquemment :

• Données d'utilisateur et d'organisation : Mettez en cache pendant des heures ou des jours, car cela change peu fréquemment
• Métadonnées de ticket : Mettez en cache les champs de ticket, les balises et les définitions de champs personnalisés
• Articles du Centre d'aide : Mettez en cache le contenu des articles avec les en-têtes de cache appropriés

Mettez en œuvre l'invalidation du cache à l'aide des webhooks Zendesk pour effacer les données mises en cache lorsque des modifications se produisent, garantissant que votre intégration reste à jour sans interrogation excessive.

Utilisation de webhooks au lieu de l'interrogation

L'interrogation de l'API pour les modifications est inefficace et consomme rapidement votre limite de débit. Les webhooks Zendesk notifient votre système lorsque des événements se produisent :

• Événements de ticket : Soyez averti lorsque des tickets sont créés, mis à jour ou résolus
• Modifications d'utilisateur : Recevez des mises à jour lorsque les profils d'utilisateur changent
• Mises à jour d'organisation : Suivez les modifications apportées à l'adhésion à l'organisation

Les webhooks éliminent le besoin d'interrogation constante, réduisant considérablement l'utilisation de l'API tout en fournissant des mises à jour en temps réel.

Exportations incrémentales pour les grands ensembles de données

Lors de la synchronisation de grands volumes de données, utilisez l'API Incremental Export (Exportation incrémentale) :

• Demandez uniquement les éléments qui ont changé depuis votre dernière synchronisation
• Utilisez la pagination basée sur le curseur pour une gestion efficace des grands ensembles de données
• Restez dans la limite de 10 requêtes par minute (30 avec l'extension High Volume)

Cette approche est beaucoup plus efficace que la récupération répétée de tous les tickets, en particulier pour les comptes avec des volumes de tickets élevés.

Source : Documentation sur les exportations incrémentales de Zendesk

Quand passer à l'API High Volume

Parfois, l'optimisation ne suffit pas. Voici comment savoir quand vous avez besoin de l'extension High Volume API. Pour un aperçu complet des capacités de Zendesk, lisez notre revue de Zendesk.

Signes que vous avez besoin de l'extension

Envisagez de mettre à niveau si vous rencontrez :

• Atteinte constante de 700 requêtes par minute sur les plans Enterprise
• Retards d'intégration affectant les opérations commerciales
• Volume de tickets croissant qui dépasse votre limite actuelle
• Plusieurs intégrations en concurrence pour le même pool de limites de débit
• Erreurs 429 fréquentes malgré les efforts d'optimisation

Tarification et exigences

L'extension High Volume API :

• Augmente votre limite à 2500 requêtes par minute
• Disponible sur les plans Zendesk Suite Growth+ et Support Professional+
• Nécessite un minimum de 10 postes d'agent
• Inclus sans frais supplémentaires avec les plans Enterprise Plus

Source : À propos des extensions Zendesk

Avant de mettre à niveau, auditez votre utilisation actuelle de l'API. De nombreuses équipes constatent qu'elles peuvent s'optimiser pour sortir des problèmes de limite de débit sans frais supplémentaires.

Alternative : Laissez eesel AI gérer les limites de débit pour vous

La création et la maintenance d'une intégration conforme aux limites de débit demandent un effort d'ingénierie important. Si vous préférez vous concentrer sur votre produit de base plutôt que de gérer les quotas d'API, nous vous proposons une alternative.

eesel AI se connecte directement à Zendesk et gère automatiquement la limitation du débit. Notre système :

• Surveille les en-têtes de limite de débit en temps réel
• Met en œuvre une mise en file d'attente et un repli intelligents des requêtes
• Utilise le traitement par lots optimisé pour minimiser les appels API
• Fournit des mises à jour basées sur des webhooks au lieu de l'interrogation
• S'adapte de manière transparente à mesure que votre volume de tickets augmente

Au lieu d'écrire du code personnalisé pour gérer les erreurs 429 et le repli exponentiel, vous configurez des automatisations en langage clair. Nous gérons la complexité technique du respect des limites de débit de Zendesk pendant que vos intégrations fonctionnent de manière fiable. Apprenez-en davantage sur nos capacités Zendesk AI Agent.

Pour les équipes qui créent des intégrations personnalisées, notre référence de l'API d'automatisation Zendesk fournit des conseils techniques supplémentaires.

Commencez à créer des intégrations Zendesk fiables dès aujourd'hui

Comprendre les limites de débit de l'API Zendesk est essentiel pour tout projet d'intégration. Les principaux points à retenir :

• Connaissez les limites de votre plan : 200 à 2500 requêtes par minute selon votre niveau
• Surveillez les en-têtes de limite de débit pour suivre l'utilisation en temps réel
• Mettez en œuvre un repli exponentiel pour les erreurs 429
• Utilisez le tableau de bord du Centre d'administration pour suivre les modèles d'utilisation
• Optimisez avec le traitement par lots, la mise en cache et les webhooks
• Envisagez l'extension High Volume API lorsque l'optimisation ne suffit pas

Que vous construisiez une intégration personnalisée ou que vous recherchiez une solution gérée, la gestion correcte des limites de débit garantit que vos flux de travail Zendesk fonctionnent sans heurts et sans interruption.

Prêt à automatiser vos flux de travail Zendesk sans vous soucier des limites de débit ? Essayez eesel AI et laissez-nous gérer la complexité de l'API pendant que vous vous concentrez sur la fourniture d'excellentes expériences client.