Développement Zoho

API Zoho CRM v8 : crédits, concurrence et quotas

Crédits API par jour selon l'édition, coût de chaque appel, limites de concurrence et neuf techniques pour ne plus être bloqué par l'API Zoho CRM.

31 octobre 2026

L'essentiel

En API v8, Zoho CRM accorde à chaque organisation un budget de crédits sur 24 heures glissantes : 50 000 crédits de base, plus 250 à 2 000 par licence selon l'édition. La plupart des appels coûtent 1 crédit, mais convertir un prospect en coûte 5, envoyer un e-mail 20 et lancer une écriture en masse 500.

Deux autres limites pèsent autant : le nombre d'appels simultanés, de 5 à 25 selon l'édition, et la pagination. Et vos fonctions Deluge puisent dans le même budget que vos intégrations.

En bref

Enterprise ou Zoho One avec 25 licences : 75 000 crédits par 24 heures.
Le compteur est glissant : il ne se remet pas à zéro à minuit.
L'erreur TOO_MANY_REQUESTS vient de la concurrence, pas du quota quotidien.
Écrire par lots de 100, lire par COQL et écouter les notifications divisent la consommation.
La documentation de Zoho se contredit selon les pages : fiez-vous à la page v8 et au tableau de bord API de votre compte.

Combien de crédits par jour selon votre édition

Le budget dépend de l'édition et du nombre de licences achetées (Zoho, API v8) :

Édition	Crédits de base	Bonus par licence	Plafond par 24 h
Standard / Starter	50 000	250	100 000
Professional	50 000	500	3 000 000
Enterprise / Zoho One	50 000	1 000	5 000 000
Ultimate / CRM Plus	50 000	2 000	Illimité

L'édition gratuite dispose de 5 000 crédits au total. Les éditions d'essai ont les mêmes limites que les éditions payantes correspondantes.

Exemple. Une PME en Enterprise avec 25 licences dispose de 50 000 + 25 × 1 000 = 75 000 crédits.

La fenêtre est glissante. Chaque appel est décompté pendant 24 heures à partir de son heure d'exécution. Il n'y a pas de remise à zéro à minuit : un pic à 10 h pèse jusqu'à 10 h le lendemain.

Attention, la documentation se contredit. La page des limites non versionnée affiche encore 15 000 crédits de base en Enterprise, 10 000 en Professional et 5 000 en Standard, avec un plafond d'un million en Enterprise (Zoho). La page de l'API v8 donne les chiffres du tableau ci-dessus. Pour votre organisation, le seul chiffre qui fait foi est celui du tableau de bord API de votre compte.

Ce que coûte chaque appel

La règle générale est d'un crédit par appel. Les exceptions sont celles qui vident un quota sans prévenir :

Appel	Crédits
Lecture d'un enregistrement, métadonnées, recherche et la plupart des autres appels	1
Création, mise à jour ou upsert	1 par tranche de 10 enregistrements, 100 au plus par appel
Requête COQL	1 jusqu'à 200 lignes, 2 jusqu'à 1 000, 3 jusqu'à 2 000
Liste filtrée par une vue personnalisée	3
Conversion d'un prospect	5
Envoi d'un e-mail	20
Lancement d'une lecture en masse (Bulk Read)	50
Nombre d'enregistrements d'un module	50
Fusion d'enregistrements	50
Conversion en masse de prospects	200
Lancement d'une écriture en masse (Bulk Write)	500
Création d'un module personnalisé	500

Source : Zoho, API v8.

Trois conséquences pratiques :

Écrire un par un coûte dix fois plus cher. Mettre à jour 100 enregistrements coûte 10 crédits en un appel groupé, 100 crédits en 100 appels.
L'e-mail par API est un gouffre. Un workflow qui envoie un e-mail par API pour chaque nouveau prospect consomme 20 crédits par prospect.
Deluge compte comme l'API. Depuis que Zoho inclut les tâches d'intégration dans le décompte, zoho.crm.searchRecords() coûte exactement autant que l'appel de recherche équivalent. La section des crédits par application et par fonction du tableau de bord montre ce que chaque fonction consomme.

La limite qu'on oublie : la concurrence

Zoho ne limite pas le nombre d'appels par minute. Il limite le nombre d'appels en cours au même moment, par organisation et par application :

Édition	Appels simultanés
Free	5
Standard / Starter	10
Professional	15
Enterprise / Zoho One	20
Ultimate / CRM Plus	25

Une seconde limite, la sous-concurrence, plafonne à 10 les appels lourds simultanés, quelle que soit l'édition :

lecture filtrée par une vue ou triée ;
conversion d'un prospect ;
création, mise à jour ou upsert de plus de 10 enregistrements ;
envoi d'e-mail ;
recherche lancée depuis une fonction ;
requête COQL et API composite.

Au-delà, Zoho répond TOO_MANY_REQUESTS. C'est l'erreur typique d'une synchronisation qui lance 30 requêtes en parallèle pour aller plus vite.

Deux détails méconnus :

les tâches d'intégration Deluge ont leur propre plafond de concurrence par organisation, aux mêmes valeurs, sans sous-concurrence ;
une requête composite consomme 5 unités de concurrence d'un coup, quel que soit le nombre de sous-requêtes qu'elle contient (Zoho).

La parade : une file d'attente avec un parallélisme plafonné sous la limite de votre édition, et une reprise progressive en cas d'erreur. L'exemple de code plus bas le montre.

Surveiller sa consommation

Trois outils suffisent pour ne plus découvrir un quota épuisé par une panne.

Le tableau de bord API, dans l'espace développeur du CRM. Il montre les crédits consommés et leur répartition par application et par fonction. C'est aussi là qu'un super-administrateur peut relever la limite : les crédits supplémentaires sont facturés chaque mois à l'usage.
L'en-tête X-API-CREDITS-REMAINING. Dès que l'organisation a consommé 50 % de ses crédits quotidiens, chaque réponse de l'API indique les crédits restants. Votre code peut le lire et ralentir de lui-même.
Une alerte à 70 %. Un script planifié qui lit cet en-tête et prévient votre équipe laisse le temps d'agir avant le blocage.

Ne confondez pas deux compteurs distincts : les crédits d'API, qui comptent les appels, et les crédits de fonctions, qui comptent les exécutions de fonctions Deluge. Ces derniers ont leur propre allocation : en Enterprise, 20 000 crédits plus 500 par licence (Zoho).

Neuf techniques pour consommer moins

Classées de la plus rentable à la plus spécifique.

Écrire par lots de 100. L'API accepte jusqu'à 100 enregistrements par création, mise à jour ou upsert, pour 1 crédit par tranche de 10. C'est le gain le plus immédiat.
Préférer l'upsert à « chercher puis écrire ». L'upsert crée ou met à jour selon un champ de dédoublonnage comme l'e-mail. Vous économisez une recherche par enregistrement.
Écouter plutôt qu'interroger. Un sondage toutes les 5 minutes, c'est 288 appels par jour et par objet surveillé. Les notifications de Zoho vous préviennent à chaque changement, à condition de renouveler l'abonnement chaque semaine.
Ne lire que ce qui a changé. L'en-tête If-Modified-Since de la lecture d'enregistrements, ou un filtre sur Modified_Time en COQL, évite de relire toute la base à chaque synchronisation.
Lire en volume avec COQL. Une requête COQL rend jusqu'à 2 000 lignes pour 3 crédits, contre 10 appels de 200 lignes en lecture classique. Elle accepte 25 critères et des jointures par les champs de recherche (Zoho).
Passer en Bulk Read au-delà de 100 000 enregistrements. La pagination classique et COQL plafonnent à 100 000 lignes par requête. Au-delà, une lecture en masse coûte 50 crédits et livre un fichier CSV de façon asynchrone.
Mettre les métadonnées en cache. Champs, modules et mises en page changent rarement. Les relire à chaque exécution est du gaspillage.
Réutiliser le jeton d'accès pendant une heure. Un jeton OAuth est valable 3 600 secondes (Zoho). En redemander un à chaque appel ralentit tout et multiplie les appels inutiles.
Enchaîner jusqu'à 5 appels avec l'API composite. Créer un enregistrement puis le mettre à jour en réutilisant son identifiant coûte 1 crédit sans annulation globale. En contrepartie, la requête prend 5 unités de concurrence.

Sur la pagination, retenez trois chiffres : 200 enregistrements par page, 2 000 avec le paramètre page, puis 100 000 au maximum avec page_token, un jeton valable 24 heures et propre à chaque utilisateur (Zoho). Le paramètre fields est obligatoire et limité à 50 champs.

Exemple : un upsert par lots qui résiste aux pics

Ce script PHP synchronise des contacts par lots de 100, dédoublonne sur l'e-mail, lit les crédits restants et attend de plus en plus longtemps quand Zoho répond TOO_MANY_REQUESTS.

<?php
// Upsert de contacts par lots de 100, avec reprise sur TOO_MANY_REQUESTS.
// $apiDomain vient de la réponse OAuth, par exemple https://www.zohoapis.eu
function upsertContacts(array $contacts, string $accessToken, string $apiDomain): array
{
    $resultats = [];
    foreach (array_chunk($contacts, 100) as $lot) {   // 100 enregistrements maximum par appel
        $corps = json_encode([
            'data' => $lot,
            'duplicate_check_fields' => ['Email'],   // dédoublonnage sur l'e-mail
            'trigger' => [],                          // aucun workflow déclenché par l'import
        ]);
        $tentative = 0;
        while (true) {
            $ch = curl_init($apiDomain . '/crm/v8/Contacts/upsert');
            curl_setopt_array($ch, [
                CURLOPT_POST           => true,
                CURLOPT_POSTFIELDS     => $corps,
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_HEADER         => true,
                CURLOPT_HTTPHEADER     => [
                    'Authorization: Zoho-oauthtoken ' . $accessToken,
                    'Content-Type: application/json',
                ],
            ]);
            $reponse = curl_exec($ch);
            $erreur  = curl_error($ch);
            $statut  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            $taille  = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
            curl_close($ch);
            if ($reponse === false) {                 // panne réseau : on note et on passe
                $resultats[] = ['statut' => 0, 'erreur' => $erreur];
                break;
            }
            $entetes = substr($reponse, 0, $taille);
            $json    = json_decode(substr($reponse, $taille), true);
            if (preg_match('/X-API-CREDITS-REMAINING:\s*(\d+)/i', $entetes, $m)) {
                error_log('Crédits API restants : ' . $m[1]);
            }
            // Trop d'appels simultanés : attente de 1, 2, 4, 8 puis 16 secondes
            $tropDAppels = $statut === 429 || (($json['code'] ?? '') === 'TOO_MANY_REQUESTS');
            if ($tropDAppels && $tentative < 5) {
                sleep(2 ** $tentative);
                $tentative++;
                continue;
            }
            $resultats[] = ['statut' => $statut, 'corps' => $json];
            break;
        }
    }
    return $resultats;
}

Le même upsert depuis une fonction Deluge, avec une connexion qui porte l'authentification :

// Upsert d'un lot de contacts : 100 enregistrements maximum par appel.
// Connexion "zoho_crm" avec le scope ZohoCRM.modules.ALL ; domaine à adapter (.eu, .com...).
lot = list();
contact = Map();
contact.put("Last_Name","Dupont");
contact.put("Email","marie.dupont@exemple.fr");
lot.add(contact);
corps = Map();
corps.put("data",lot);
corps.put("duplicate_check_fields",{"Email"});
corps.put("trigger",list());
reponse = invokeurl
[
	url :"https://www.zohoapis.eu/crm/v8/Contacts/upsert"
	type :POST
	parameters:corps.toString()
	connection:"zoho_crm"
];
info reponse;

Depuis Deluge, cet appel consomme les mêmes crédits qu'un appel externe : le gain vient du regroupement par 100, pas du langage.

Quand changer d'architecture

Optimiser les appels suffit souvent. Mais certains signaux montrent que l'architecture elle-même est en cause :

la consommation dépasse 70 % du quota la plupart des jours ;
TOO_MANY_REQUESTS apparaît chaque semaine dans les journaux ;
des fonctions de workflow frôlent la limite de 30 secondes ;
des synchronisations nocturnes échouent ou se chevauchent ;
vous achetez des crédits supplémentaires tous les mois.

La réponse type tient en trois mouvements : passer au mode événementiel (notifications plutôt que sondage), mettre une file d'attente entre Zoho et vos outils, et déplacer les traitements lourds hors de Deluge, sur un service comme Zoho Catalyst. Acheter des crédits ne vient qu'après : sinon, vous payez pour du gaspillage.

Vos intégrations Zoho consomment trop ?

SquadNovia analyse votre tableau de bord API, repère les appels qui coûtent le plus et réécrit les intégrations en cause. Pour un correctif ciblé, une banque de 10 heures suffit souvent.

Banque d'heures · Audit complet

Questions fréquentes

Les crédits API de Zoho CRM se réinitialisent-ils à minuit ?

Non. Chaque appel est décompté pendant 24 heures à partir de son exécution. Les crédits se libèrent donc au fil de l'eau, pas d'un coup.

Mes fonctions Deluge consomment-elles des crédits API ?

Oui. Les tâches d'intégration comme zoho.crm.createRecord consomment les mêmes crédits que l'API équivalente. Les exécutions de fonctions ont en plus leur propre compteur.

Combien d'enregistrements puis-je lire par l'API ?

200 par appel, 2 000 avec le paramètre page, puis jusqu'à 100 000 avec page_token. En COQL, 2 000 lignes par appel et 100 000 par critère. Au-delà, utilisez la lecture en masse.

Que faire face à l'erreur TOO_MANY_REQUESTS ?

Réduire le nombre d'appels simultanés sous la limite de votre édition et réessayer avec un délai croissant. Cette erreur vient de la concurrence, pas du quota quotidien.

Peut-on acheter des crédits supplémentaires ?

Oui. Un super-administrateur relève la limite depuis le tableau de bord API, et les crédits consommés sont facturés chaque mois. Optimisez d'abord : c'est presque toujours moins cher.

Une sandbox a-t-elle son propre quota ?

Une sandbox est une organisation à part entière, avec ses propres jetons. Ses appels passent par l'adresse sandbox.zohoapis.{domaine}, disponible depuis l'API v6.

Sources

Pages consultées le 20 octobre 2026.