Limites de débit

Les limites gardent Matchai rapide pour tout le monde. Cette page indique ce que les interfaces publiques permettent aujourd'hui, et comment l'API Matchai prévue signalera et appliquera ses limites.

Sur les interfaces publiquesCopier le lien de cette section

Ces limites s'appliquent aux interfaces que vous pouvez utiliser dès aujourd'hui sans clé. Chacune est comptée par adresse appelante : l'adresse d'où proviennent vos requêtes. Les appelants qui partagent une même adresse, comme le réseau d'un bureau ou un assistant hébergé, partagent un seul quota.

Quelques précisions :

• La limite du serveur MCP ne compte que tools/call. L'établissement de la liaison, tools/list et les autres méthodes ne sont pas comptés. C'est une protection contre les abus, fixée assez haut pour qu'une plateforme d'assistant très sollicitée ne l'atteigne pas.
• La recherche d'inscriptions peut aussi répondre 503. Quand la recherche est temporairement indisponible, elle répond 503 avec l'erreur unavailable et un Retry-After de 30 secondes. Attendez ce délai, puis réessayez.
• Les pages lisibles par l'IA n'ont pas de limite chiffrée par minute, mais vous demandent d'être courtois : environ une requête par seconde par hôte. Pour lire un site entier, récupérez son llms-full.txt au lieu de l'explorer page par page. Après un 429, attendez la durée indiquée par Retry-After. Les fichiers de découverte changent au plus environ une fois par minute, alors les interroger plus souvent renvoie le même contenu.

Consultez la recherche d'inscriptions et le serveur MCP pour le portrait complet.

Gérer une limite dans votre codeCopier le lien de cette section

async function ask(query) {
  const response = await fetch(`https://matchai.co/ask?query=${encodeURIComponent(query)}`);

  if (response.status === 429 || response.status === 503) {
    const wait = Number(response.headers.get('Retry-After') ?? 60);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    return ask(query); // Try once more after the wait.
  }

  return response.json();
}

Dans du vrai code, ajoutez un compteur, pour qu'une requête qui échoue sans cesse finisse par abandonner.

Dans l'API MatchaiCopier le lien de cette section

L'API Matchai limite les requêtes par connexion : un compte Matchai connecté à une application. Les chiffres ne sont pas encore publiés ici. Ne les codez pas en dur : l'API vous indique où vous en êtes dans chaque réponse.

En-têtes de limite de débitCopier le lien de cette section

Chaque réponse porte trois en-têtes :

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 41
Matchai-Request-Id: req_7Hq2LmZ9xV4c

Les nombres ci-dessus sont un exemple. Ce n'est pas la vraie limite.

Quand vous dépassez la limiteCopier le lien de cette section

Une requête au-delà de la limite est refusée avec 429 et ne fait rien. La réponse porte Retry-After, le nombre de secondes à attendre :

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Try again in 20 seconds.",
    "doc_url": "https://matchai.co/docs/developers/errors#rate_limited",
    "request_id": "req_7Hq2LmZ9xV4c"
  }
}

Un 429 peut être réessayé sans risque. Attendez la durée de Retry-After, puis renvoyez la requête avec le même Idempotency-Key, pour que rien ne se fasse deux fois. La section Réessayer sans risque donne un exemple complet.

Qui partage une limiteCopier le lien de cette section

• Toutes les clés d'un même compte partagent une seule limite, parce qu'elles appartiennent à une seule connexion. Une deuxième clé ne donne pas plus de marge. Consultez Clés d'API.
• Deux professionnels connectés à la même application ont des limites distinctes. La matinée chargée d'un courtier ne ralentit pas la connexion d'un autre courtier.
• Les opérations publiques fonctionnent sans identifiant de connexion, avec des limites plus basses. Consulter le profil ou les inscriptions publiés d'un professionnel ne demande aucune clé. Ces requêtes sont comptées par adresse IP, et envoyer une clé ou un jeton relève la limite. Elles sont marquées Free (gratuit) dans la référence de l'API.

Les limites de débit ne sont pas des limites d'énergieCopier le lien de cette section

Une action qui utilise de l'Énergie Matchai peut être refusée pour deux autres raisons, et aucune n'est un 429 :

• Le compte n'a plus d'énergie : 402 avec le code insufficient_energy.
• Le titulaire du compte a fixé une limite d'énergie pour votre connexion, et vous l'avez atteinte : 402 avec le code energy_limit_reached.

Attendre ne règle ni l'un ni l'autre. Consultez Erreurs.

Rester bien sous la limiteCopier le lien de cette section

• Lisez les en-têtes. Ralentissez quand RateLimit-Remaining est bas, et faites une pause jusqu'à RateLimit-Reset quand il atteint zéro.
• Écoutez au lieu d'interroger. Les webhooks vous avisent quand un prospect arrive ou qu'une inscription change, sans aucune requête.
• Synchronisez ce qui a changé. Utilisez updated_since sur les points de terminaison de liste, et demandez des pages de limit=100, la plus grande taille de page.
• Étalez le travail en lot. Importer une centaine de contacts se fait en file d'attente, pas en rafale.
• Ne répétez que ce qui a échoué. Les clés d'idempotence vous permettent de réessayer une seule requête sans risque.

export async function pacedFetch(url, init) {
  const response = await fetch(url, init);

  const remaining = Number(response.headers.get('RateLimit-Remaining'));
  const reset = Number(response.headers.get('RateLimit-Reset'));

  // Nearly out of requests: wait for the window to reset before the next call.
  if (remaining <= 1 && reset > 0) {
    await new Promise((resolve) => setTimeout(resolve, reset * 1000));
  }

  return response;
}