ArgorantDocs

Erreurs et limites

L'unique format d'erreur, chaque code d'erreur, l'identifiant de requête, les limites de requêtes par forfait, les limites sur les recherches et les comptages, les limites quotidiennes, la pagination et les nouvelles tentatives sans risque.

Un format d'erreur unique

Toutes les réponses d'erreur ont la même forme. Lisez error.code pour décider quoi faire et affichez error.message aux personnes. Le message tient en une phrase simple.

JSON
{
  "error": {
    "code": "insufficient_credits",
    "message": "Revealing these people costs 1 credit each and the account has none left. Pick a plan at https://argorant.com/pricing.",
    "details": { "needed": 25, "balance": 0 }
  },
  "request_id": "req_8f2c1d9e0b7a4c3e9f1a2b3c4d5e6f70",
  "detail": "..."
}

detail contient l'ancienne forme de l'erreur pour les clients écrits avant ce format. Le nouveau code doit lire error.

Codes d'erreur

CodeStatutCe que cela signifie et quoi faire
invalid_request400Il manque quelque chose à la requête ou une valeur est incorrecte. Le message indique quoi corriger.
launch_blocked400La campagne ne peut pas encore être lancée. details.blockers liste ce qui manque.
unauthorized401Aucune clé API, ou la clé est incorrecte ou révoquée.
api_key_required401Cette route nécessite une clé API ou une connexion via connecteur, pas une session de navigateur.
plan_required402Le forfait du compte n'inclut pas cela. Le message indique le forfait qui l'inclut. Une clé d'un compte sans forfait et sans crédits reçoit cette erreur à chaque appel.
insufficient_credits402Pas assez de crédits pour cet appel. details indique combien il en faut. Rien n'a été facturé.
scope_missing403Il manque à la clé un scope nécessaire à cet appel. Créez une clé avec ce scope.
permission_missing403Votre rôle dans l'espace de travail ne permet pas cette action.
forbidden403Cette action n'est pas autorisée pour ce compte.
not_found404Cet élément n'existe pas dans votre espace de travail. Les éléments d'autres espaces de travail répondent de la même façon.
route_not_found404Cet endpoint n'existe pas. Vérifiez le chemin dans la référence.
method_not_allowed405Le chemin existe, mais pas avec cette méthode HTTP. details.allowed liste les méthodes.
conflict409L'élément est dans un état qui ne le permet pas, par exemple la suppression d'une campagne en cours.
idempotency_conflict409Cette Idempotency-Key a déjà été utilisée avec un autre corps.
idempotency_in_progress409Une requête avec cette Idempotency-Key est encore en cours. Attendez et réessayez.
gone410L'élément a expiré, par exemple un fichier d'export plus ancien que sa durée de conservation.
quote_expired410Le devis est trop ancien. Demandez un nouveau devis et confirmez à nouveau.
validation_error422Un champ a le mauvais type ou est absent. details.fields liste chaque problème.
access_key_activation_required428Cette clé d'accès reçue par invitation n'est pas encore active. Confirmez d'abord l'e-mail dans details.claim_url.
rate_limited429Trop de requêtes cette minute, en 10 secondes, ou trop de recherches et de comptages cette minute, ou plus de 200 personnes débloquées en une minute. Attendez Retry-After secondes.
daily_limit_reached429Une limite quotidienne est atteinte : la limite de la clé pour ce type d'appel, ou les nouveaux e-mails par jour d'un compte sans forfait. details.action l'indique. Elle est réinitialisée à minuit UTC.
internal_error500Quelque chose a échoué de notre côté. Réessayez ; indiquez l'identifiant de requête si l'erreur persiste.
unavailable503Une partie du service est occupée ou en pause. Réessayez dans une minute.
confirmation_required400Une commande nécessite confirmed=true, envoyé uniquement après que la personne qui paie a dit oui.
invalid_webhook_url400L'adresse du webhook doit être une adresse https:// publique.
invalid_webhook_events400Un nom d'événement est inconnu ou aucun événement n'a été indiqué. details.invalid liste les noms inconnus.
webhook_limit_reached400Vous avez 10 webhooks activés, ou 50 au total en comptant ceux qui sont désactivés. Supprimez-en un ou désactivez-en un d'abord. Chaque membre de l'équipe a les siens.
event_not_subscribed400Un appel de test a indiqué un événement que le webhook ne reçoit pas. details.events liste ceux qu'il reçoit.
company_credits_required402Un profil d'entreprise complet coûte des crédits et le compte n'en a pas assez. details.teaser contient la partie gratuite ; rien n'a été facturé.
search_busy503La recherche est occupée en ce moment. Réessayez dans quelques secondes.
phones_not_in_plan402Les numéros de téléphone sont inclus à partir du forfait Pro. Rien n'a été facturé.
card_not_charged402La carte enregistrée n'a pas été débitée. Rien n'a été acheté ; payez plutôt via un lien de paiement.
owner_only403Seul le propriétaire de l'espace de travail peut faire cela, par exemple commander ou résilier des boîtes mail.
quote_not_found404Le devis n'existe pas ou appartient à quelqu'un d'autre. Demandez un nouveau devis.
charge_in_progress409Ce devis est en cours de facturation. Vérifiez la commande dans un instant.
not_enough_names409Pas assez de noms de domaine disponibles ont été trouvés. Envoyez vous-même quelques domaines.
not_paid409La commande n'est pas encore payée, il n'y a donc rien à annuler.
reason_required422La résiliation de boîtes mail nécessite un motif parmi les choix proposés.
not_connected409Cet outil n'est pas encore connecté. Connectez-le d'abord dans Paramètres, Outils connectés.
unsupported_tool409Cet outil connecté ne peut pas recevoir de personnes directement. Envoyez-lui plutôt un export depuis la page Exports.
tool_key_rejected409L'outil connecté n'a pas accepté la clé enregistrée. Reconnectez-le dans Paramètres, Outils connectés.
price_mismatch409Le prix que vous avez montré à la personne n'est pas le prix du devis. Montrez le prix du devis et demandez à nouveau.
quote_other_session409Le devis a été établi avec une autre clé ou une autre connexion. Demandez un nouveau devis ici et confirmez à nouveau.
export_failed409L'export ne s'est pas terminé, il n'y a donc rien à envoyer. Relancez l'export.
sign_in_failed422Le serveur de messagerie n'a pas accepté la connexion, la boîte mail n'a donc pas été connectée. details.test indique, pour l'envoi et pour la lecture des réponses, ce qui n'a pas fonctionné.
campaign_not_started409La campagne est un brouillon, il n'y a donc rien à mettre en pause. Lancez-la d'abord.
finder_rate_limit429Plus de 30 recherches d'e-mail unitaires cette minute. Attendez Retry-After secondes.
finder_daily_limit4292 000 recherches d'e-mail aujourd'hui. La limite est réinitialisée à minuit UTC.
finder_miss_rate_throttle429La plupart des recherches récentes n'ont rien trouvé, elles sont donc ralenties à 20 par heure pendant un moment. Vérifiez les noms et les domaines.

Certaines opérations ajoutent leur propre code, comme confirmation_required ou quote_not_found. Chaque opération liste ses codes dans la référence. Traitez un code que vous ne connaissez pas selon son statut HTTP.

L'identifiant de requête

Chaque réponse contient un en-tête X-Request-Id, et chaque erreur le reprend dans request_id. Envoyez votre propre identifiant dans l'en-tête X-Request-Id (8 à 64 lettres, chiffres, points, tirets ou traits de soulignement) pour retrouver un appel dans vos propres logs. Indiquez l'identifiant quand vous demandez de l'aide.

Requêtes par minute

Chaque clé peut envoyer ce nombre de requêtes par minute, et jusqu'au second nombre sur n'importe quelle période de 10 secondes.

ForfaitRequêtes par minuteEn 10 secondes
Sans forfait, clé API ou CLI3015
Sans forfait, assistant IA6020
Starter6015
Pro24060
Scale600150
Hyperscale1 200300

Sans forfait couvre les 7 premiers jours d'un compte qui n'a pas encore choisi de forfait, ainsi que les comptes qui utilisent des crédits achetés auparavant. Un essai d'un forfait a les limites de ce forfait. Une clé d'un compte sans forfait et sans crédits reçoit 402 plan_required à chaque appel, GET /api/v1/account compris.

Chaque réponse à un appel avec clé contient X-RateLimit-Limit (requêtes par minute), X-RateLimit-Remaining (requêtes restantes cette minute) et X-RateLimit-Reset (secondes avant que la minute ne recommence). Au-delà de l'une ou l'autre limite, vous recevez 429 rate_limited avec un en-tête Retry-After. Attendez ce nombre de secondes, puis réessayez.

Le déblocage de personnes a une limite de plus sur tous les forfaits : un compte débloque jusqu'à 200 personnes par minute. Au-delà, vous recevez aussi 429 rate_limited.

Recherches et comptages

Les recherches, les comptages et les aperçus sont gratuits. Ils sont limités par compte, sur l'ensemble de ses clés et du connecteur, donc une deuxième clé n'en ajoute pas.

ForfaitPar minuteComptages par jourLignes d'aperçu par jour
Sans forfait, clé API ou CLI10500500
Sans forfait, assistant IA201 0001 000
Starter30aucune limiteaucune limite
Pro60aucune limiteaucune limite
Scale90aucune limiteaucune limite
Hyperscale120aucune limiteaucune limite

Sans forfait, les recherches et les comptages contiennent aussi X-RateLimit-Daily-Limit et X-RateLimit-Daily-Remaining. Un aperçu contient jusqu'à 10 personnes par appel.

Limites quotidiennes par clé

Sans forfait, chaque clé a aussi des limites quotidiennes. Avec un forfait, seule la recherche d'e-mail en a une ; les crédits encadrent le reste. Les limites quotidiennes sont réinitialisées à minuit UTC. GET /api/v1/account indique ce qu'il reste aujourd'hui.

QuoiPar jourPar appel
Personnes débloquées, par filtres100 (aucune limite avec un forfait)25
Lignes d'export50 000 (aucune limite avec un forfait)50 000 par fichier, 500 000 par lot
Recherches d'e-mail2 00030 par minute, listes jusqu'à 10 000 lignes

Un compte sans forfait trouve aussi jusqu'à 10 nouveaux e-mails par jour au total : les déblocages, les résultats de la recherche d'e-mail et les lignes d'export comptent ensemble, et un e-mail que le compte avait déjà ne compte pas.

Au-delà d'une limite quotidienne, vous recevez 429 daily_limit_reached. Pour plus de personnes que la limite quotidienne de déblocage, enregistrez une liste, exportez-la ou ajoutez-la à une campagne ; ces chemins sont faits pour des milliers de personnes. La recherche d'e-mail répond avec ses propres codes : finder_rate_limit (par minute), finder_daily_limit (par jour) et finder_miss_rate_throttle (la plupart des recherches n'ont rien trouvé).

Pagination

Chaque liste accepte limit et cursor. La réponse garde sa propre clé (par exemple campaigns ou people) et ajoute total, limit, offset, next_cursor et has_more. Passez next_cursor comme cursor pour obtenir la page suivante ; il vaut null sur la dernière page. offset fonctionne aussi, si vous préférez compter les lignes vous-même.

Certaines listes s'arrêtent plus tôt ou se paginent à leur façon. Les personnes d'une campagne se paginent avec after défini sur next_after, dans un ordre fixe, et ces pages ne contiennent pas de next_cursor. Les réponses d'une campagne se paginent de la même façon avec after et next_after. La liste des campagnes atteint les 500 premières campagnes ; cursor pagine au sein de celles-ci. La boîte de réception, les réponses d'une campagne et les personnes d'une campagne acceptent aussi un filtre de date (updated_after et received_after, ou created_after) au format ISO 8601.

Shell
curl "https://app.argorant.com/api/v1/campaigns?limit=25" -H "Authorization: Bearer $ARGORANT_API_KEY"
curl "https://app.argorant.com/api/v1/campaigns?limit=25&cursor=bzoyNQ" -H "Authorization: Bearer $ARGORANT_API_KEY"

Quand total_is_estimate vaut true, total est un minimum, par exemple quand une liste a atteint sa taille maximale.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key avec chaque écriture : création, modification, suppression, réponse, transfert et tout ce qui dépense des crédits ou de l'argent. Utilisez une nouvelle valeur aléatoire pour chaque nouvelle action et la même valeur quand vous la réessayez.

  • La même clé et le même corps dans les 24 heures renvoient la première réponse, avec l'en-tête Idempotent-Replayed: true. Rien n'est fait deux fois.
  • La même clé avec un autre corps répond 409 idempotency_conflict.
  • Tant que la première requête est en cours, une nouvelle tentative répond 409 idempotency_in_progress. Attendez un instant et réessayez.
  • Les erreurs ne sont pas enregistrées, vous pouvez donc corriger le problème et réessayer avec la même clé.
Shell
curl -X POST "https://app.argorant.com/api/v1/exports" \
  -H "Authorization: Bearer $ARGORANT_API_KEY" \
  -H "Idempotency-Key: export-cfo-germany-2026-10-07" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"title":"CFO","country":"Germany"},"limit":500}'

Campagnes qui ne peuvent pas être lancées

POST /api/v1/campaigns/{id}/launch répond launch_blocked tant que quelque chose manque, par exemple un e-mail, une boîte mail qui a encore de la marge aujourd'hui, ou des personnes. details.blockers liste chaque point en mots simples. GET /api/v1/campaigns/{id} affiche la même liste dans launch_blockers, pour que vous puissiez tout corriger avant d'essayer.

Sur cette page