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.
{
"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
| Code | Statut | Ce que cela signifie et quoi faire |
|---|---|---|
invalid_request | 400 | Il manque quelque chose à la requête ou une valeur est incorrecte. Le message indique quoi corriger. |
launch_blocked | 400 | La campagne ne peut pas encore être lancée. details.blockers liste ce qui manque. |
unauthorized | 401 | Aucune clé API, ou la clé est incorrecte ou révoquée. |
api_key_required | 401 | Cette route nécessite une clé API ou une connexion via connecteur, pas une session de navigateur. |
plan_required | 402 | Le 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_credits | 402 | Pas assez de crédits pour cet appel. details indique combien il en faut. Rien n'a été facturé. |
scope_missing | 403 | Il manque à la clé un scope nécessaire à cet appel. Créez une clé avec ce scope. |
permission_missing | 403 | Votre rôle dans l'espace de travail ne permet pas cette action. |
forbidden | 403 | Cette action n'est pas autorisée pour ce compte. |
not_found | 404 | Cet é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_found | 404 | Cet endpoint n'existe pas. Vérifiez le chemin dans la référence. |
method_not_allowed | 405 | Le chemin existe, mais pas avec cette méthode HTTP. details.allowed liste les méthodes. |
conflict | 409 | L'élément est dans un état qui ne le permet pas, par exemple la suppression d'une campagne en cours. |
idempotency_conflict | 409 | Cette Idempotency-Key a déjà été utilisée avec un autre corps. |
idempotency_in_progress | 409 | Une requête avec cette Idempotency-Key est encore en cours. Attendez et réessayez. |
gone | 410 | L'élément a expiré, par exemple un fichier d'export plus ancien que sa durée de conservation. |
quote_expired | 410 | Le devis est trop ancien. Demandez un nouveau devis et confirmez à nouveau. |
validation_error | 422 | Un champ a le mauvais type ou est absent. details.fields liste chaque problème. |
access_key_activation_required | 428 | Cette clé d'accès reçue par invitation n'est pas encore active. Confirmez d'abord l'e-mail dans details.claim_url. |
rate_limited | 429 | Trop 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_reached | 429 | Une 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_error | 500 | Quelque chose a échoué de notre côté. Réessayez ; indiquez l'identifiant de requête si l'erreur persiste. |
unavailable | 503 | Une partie du service est occupée ou en pause. Réessayez dans une minute. |
confirmation_required | 400 | Une commande nécessite confirmed=true, envoyé uniquement après que la personne qui paie a dit oui. |
invalid_webhook_url | 400 | L'adresse du webhook doit être une adresse https:// publique. |
invalid_webhook_events | 400 | Un nom d'événement est inconnu ou aucun événement n'a été indiqué. details.invalid liste les noms inconnus. |
webhook_limit_reached | 400 | Vous 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_subscribed | 400 | Un 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_required | 402 | Un 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_busy | 503 | La recherche est occupée en ce moment. Réessayez dans quelques secondes. |
phones_not_in_plan | 402 | Les numéros de téléphone sont inclus à partir du forfait Pro. Rien n'a été facturé. |
card_not_charged | 402 | La carte enregistrée n'a pas été débitée. Rien n'a été acheté ; payez plutôt via un lien de paiement. |
owner_only | 403 | Seul le propriétaire de l'espace de travail peut faire cela, par exemple commander ou résilier des boîtes mail. |
quote_not_found | 404 | Le devis n'existe pas ou appartient à quelqu'un d'autre. Demandez un nouveau devis. |
charge_in_progress | 409 | Ce devis est en cours de facturation. Vérifiez la commande dans un instant. |
not_enough_names | 409 | Pas assez de noms de domaine disponibles ont été trouvés. Envoyez vous-même quelques domaines. |
not_paid | 409 | La commande n'est pas encore payée, il n'y a donc rien à annuler. |
reason_required | 422 | La résiliation de boîtes mail nécessite un motif parmi les choix proposés. |
not_connected | 409 | Cet outil n'est pas encore connecté. Connectez-le d'abord dans Paramètres, Outils connectés. |
unsupported_tool | 409 | Cet outil connecté ne peut pas recevoir de personnes directement. Envoyez-lui plutôt un export depuis la page Exports. |
tool_key_rejected | 409 | L'outil connecté n'a pas accepté la clé enregistrée. Reconnectez-le dans Paramètres, Outils connectés. |
price_mismatch | 409 | Le prix que vous avez montré à la personne n'est pas le prix du devis. Montrez le prix du devis et demandez à nouveau. |
quote_other_session | 409 | Le devis a été établi avec une autre clé ou une autre connexion. Demandez un nouveau devis ici et confirmez à nouveau. |
export_failed | 409 | L'export ne s'est pas terminé, il n'y a donc rien à envoyer. Relancez l'export. |
sign_in_failed | 422 | Le 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_started | 409 | La campagne est un brouillon, il n'y a donc rien à mettre en pause. Lancez-la d'abord. |
finder_rate_limit | 429 | Plus de 30 recherches d'e-mail unitaires cette minute. Attendez Retry-After secondes. |
finder_daily_limit | 429 | 2 000 recherches d'e-mail aujourd'hui. La limite est réinitialisée à minuit UTC. |
finder_miss_rate_throttle | 429 | La 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.
| Forfait | Requêtes par minute | En 10 secondes |
|---|---|---|
| Sans forfait, clé API ou CLI | 30 | 15 |
| Sans forfait, assistant IA | 60 | 20 |
| Starter | 60 | 15 |
| Pro | 240 | 60 |
| Scale | 600 | 150 |
| Hyperscale | 1 200 | 300 |
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.
| Forfait | Par minute | Comptages par jour | Lignes d'aperçu par jour |
|---|---|---|---|
| Sans forfait, clé API ou CLI | 10 | 500 | 500 |
| Sans forfait, assistant IA | 20 | 1 000 | 1 000 |
| Starter | 30 | aucune limite | aucune limite |
| Pro | 60 | aucune limite | aucune limite |
| Scale | 90 | aucune limite | aucune limite |
| Hyperscale | 120 | aucune limite | aucune 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.
| Quoi | Par jour | Par appel |
|---|---|---|
| Personnes débloquées, par filtres | 100 (aucune limite avec un forfait) | 25 |
| Lignes d'export | 50 000 (aucune limite avec un forfait) | 50 000 par fichier, 500 000 par lot |
| Recherches d'e-mail | 2 000 | 30 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.
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é.
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.
Authentification
Les clés API, l'URL de base, ce que permet chaque scope de clé et comment les agents IA se connectent sans clé.
Guides
Des guides pas à pas pour ce que l'on fait le plus souvent avec Argorant : le premier appel, trouver des personnes et leur écrire, les réponses, les crédits, les boîtes mail et les webhooks.