ArgorantDocs

Fouten en limieten

De ene foutvorm, elke foutcode, de request-id, requestlimieten per plan, limieten op zoekopdrachten en tellingen, daglimieten, pagina's en veilige herhalingen.

Eén foutvorm

Elke foutresponse ziet er hetzelfde uit. Lees error.code om te bepalen wat je doet, en toon error.message aan mensen. Het bericht is één eenvoudige zin.

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 bevat de oudere vorm van de fout, voor clients die vóór deze vorm zijn geschreven. Nieuwe code hoort error te lezen.

Foutcodes

CodeStatusWat het betekent en wat je doet
invalid_request400Het request mist iets of een waarde klopt niet. Het bericht zegt wat je moet aanpassen.
launch_blocked400De campagne kan nog niet starten. details.blockers somt op wat er ontbreekt.
unauthorized401Geen API-sleutel, of een onjuiste of ingetrokken sleutel.
api_key_required401Deze route heeft een API-sleutel of een connector-login nodig, geen browsersessie.
plan_required402Het plan van het account bevat dit niet. Het bericht noemt het plan dat het wel bevat. Een sleutel van een account zonder plan en zonder credits krijgt deze code bij elke aanroep.
insufficient_credits402Niet genoeg credits voor deze aanroep. details zegt hoeveel er nodig zijn. Er is niets afgerekend.
scope_missing403De sleutel mist een scope die deze aanroep nodig heeft. Maak een sleutel aan met die scope.
permission_missing403Je rol in de workspace staat deze actie niet toe.
forbidden403Deze actie is niet toegestaan voor dit account.
not_found404Dit item bestaat niet in je workspace. Items van andere workspaces geven hetzelfde antwoord.
route_not_found404Dit endpoint bestaat niet. Vergelijk het pad met de referentie.
method_not_allowed405Het pad bestaat, maar niet met deze HTTP-methode. details.allowed somt de methodes op.
conflict409Het item is in een staat die dit niet toestaat, bijvoorbeeld bij het verwijderen van een lopende campagne.
idempotency_conflict409Deze Idempotency-Key is al gebruikt met een andere body.
idempotency_in_progress409Een request met deze Idempotency-Key loopt nog. Wacht en probeer het opnieuw.
gone410Het item is verlopen, bijvoorbeeld een exportbestand dat ouder is dan zijn bewaartermijn.
quote_expired410De offerte is te oud. Vraag een nieuwe offerte op en bevestig opnieuw.
validation_error422Een veld heeft het verkeerde type of ontbreekt. details.fields somt elk probleem op.
access_key_activation_required428Deze uitgenodigde toegangssleutel is nog niet actief. Bevestig eerst het e-mailadres in details.claim_url.
rate_limited429Te veel requests deze minuut of in 10 seconden, te veel zoekopdrachten en tellingen deze minuut, of meer dan 200 vrijgegeven mensen per minuut. Wacht Retry-After seconden.
daily_limit_reached429Een daglimiet is op: de limiet van de sleutel voor dit soort aanroep, of het aantal nieuwe e-mailadressen per dag van een account zonder plan. details.action noemt welke. De limiet wordt om middernacht UTC teruggezet.
internal_error500Er is aan onze kant iets misgegaan. Probeer het opnieuw; vermeld de request-id als het blijft mislukken.
unavailable503Een deel van de dienst is druk of gepauzeerd. Probeer het over een minuut opnieuw.
confirmation_required400Een bestelling heeft confirmed=true nodig, pas verstuurd nadat de persoon die betaalt ja heeft gezegd.
invalid_webhook_url400Het webhookadres moet een openbaar https://-adres zijn.
invalid_webhook_events400Een eventnaam is onbekend of er is geen event opgegeven. details.invalid somt de onbekende namen op.
webhook_limit_reached400Je hebt 10 webhooks aanstaan, of 50 in totaal samen met de uitgeschakelde. Verwijder er eerst één of zet er één uit. Elk teamlid heeft zijn eigen webhooks.
event_not_subscribed400Een testaanroep noemde een event dat de webhook niet ontvangt. details.events somt de events op die hij wel ontvangt.
company_credits_required402Een volledig bedrijfsprofiel kost credits en het account heeft er te weinig. details.teaser bevat het gratis deel; er is niets afgerekend.
search_busy503Zoeken is op dit moment druk. Probeer het over een paar seconden opnieuw.
phones_not_in_plan402Telefoonnummers horen bij het Pro-plan. Er is niets afgerekend.
card_not_charged402De opgeslagen kaart is niet belast. Er is niets gekocht; betaal in plaats daarvan via een betaallink.
owner_only403Alleen de eigenaar van de workspace kan dit doen, bijvoorbeeld mailboxen bestellen of opzeggen.
quote_not_found404De offerte bestaat niet of is van iemand anders. Vraag een nieuwe offerte op.
charge_in_progress409Deze offerte wordt nu afgerekend. Bekijk de bestelling zo meteen.
not_enough_names409Er zijn niet genoeg vrije domeinnamen gevonden. Stuur zelf een paar domeinen mee.
not_paid409De bestelling is nog niet betaald, dus er is niets om op te zeggen.
reason_required422Voor het opzeggen van mailboxen is een reden uit de gegeven keuzes nodig.
not_connected409Die tool is nog niet gekoppeld. Koppel hem eerst in Instellingen, Gekoppelde tools.
unsupported_tool409Deze gekoppelde tool kan niet direct mensen ontvangen. Stuur hem in plaats daarvan een export vanaf de pagina Exports.
tool_key_rejected409De gekoppelde tool accepteerde de opgeslagen sleutel niet. Koppel hem opnieuw in Instellingen, Gekoppelde tools.
price_mismatch409De prijs die je de persoon hebt getoond, is niet de geoffreerde prijs. Toon de geoffreerde prijs en vraag het opnieuw.
quote_other_session409De offerte is gemaakt met een andere sleutel of verbinding. Vraag hier een nieuwe offerte op en bevestig opnieuw.
export_failed409De export is niet afgerond, dus er is niets om te versturen. Voer de export opnieuw uit.
sign_in_failed422De mailserver accepteerde de login niet, dus de mailbox is niet gekoppeld. details.test zegt voor het versturen en voor het lezen van antwoorden wat er misging.
campaign_not_started409De campagne is een concept, dus er is niets om te pauzeren. Start hem eerst.
finder_rate_limit429Meer dan 30 losse zoekopdrachten in de e-mailfinder deze minuut. Wacht Retry-After seconden.
finder_daily_limit4292.000 zoekopdrachten in de e-mailfinder vandaag. De limiet wordt om middernacht UTC teruggezet.
finder_miss_rate_throttle429De meeste recente zoekopdrachten vonden niets, dus zoekopdrachten worden een tijdje vertraagd tot 20 per uur. Controleer de namen en domeinen.

Sommige bewerkingen voegen een eigen code toe, zoals confirmation_required of quote_not_found. Elke bewerking somt haar codes op in de referentie. Behandel een code die je niet kent volgens de HTTP-status.

De request-id

Elke response bevat een header X-Request-Id, en elke fout herhaalt die als request_id. Stuur je eigen id mee in de header X-Request-Id (8 tot 64 letters, cijfers, punten, streepjes of underscores) om een aanroep in je eigen logs terug te vinden. Vermeld de id als je om hulp vraagt.

Requests per minuut

Elke sleutel mag zoveel requests per minuut sturen, en in elke 10 seconden maximaal het tweede getal.

PlanRequests per minuutIn 10 seconden
Zonder plan, API-sleutel of CLI3015
Zonder plan, AI-assistent6020
Starter6015
Pro24060
Scale600150
Hyperscale1.200300

Zonder plan geldt voor de eerste 7 dagen van een account dat nog geen plan heeft gekozen, en voor accounts die eerder gekochte credits gebruiken. Een proefperiode van een plan heeft de limieten van dat plan. Een sleutel van een account zonder plan en zonder credits krijgt 402 plan_required bij elke aanroep, ook bij GET /api/v1/account.

Elke response op een aanroep met een sleutel bevat X-RateLimit-Limit (requests per minuut), X-RateLimit-Remaining (requests over deze minuut) en X-RateLimit-Reset (seconden tot de minuut opnieuw begint). Boven een van beide limieten krijg je 429 rate_limited met een header Retry-After. Wacht zoveel seconden en probeer het dan opnieuw.

Mensen vrijgeven heeft op elk plan nog één limiet: een account geeft maximaal 200 mensen per minuut vrij. Daarboven krijg je ook 429 rate_limited.

Zoekopdrachten en tellingen

Zoekopdrachten, tellingen en voorbeelden zijn gratis. Ze zijn per account beperkt, over al zijn sleutels en de connector samen, dus een tweede sleutel levert er niet meer op.

PlanPer minuutTellingen per dagVoorbeeldrijen per dag
Zonder plan, API-sleutel of CLI10500500
Zonder plan, AI-assistent201.0001.000
Starter30geen limietgeen limiet
Pro60geen limietgeen limiet
Scale90geen limietgeen limiet
Hyperscale120geen limietgeen limiet

Zonder plan bevatten zoekopdrachten en tellingen ook X-RateLimit-Daily-Limit en X-RateLimit-Daily-Remaining. Een voorbeeld bevat maximaal 10 mensen per aanroep.

Daglimieten per sleutel

Zonder plan heeft elke sleutel ook daglimieten. Op een plan heeft alleen de e-mailfinder er een; voor de rest zijn je credits de grens. Daglimieten worden om middernacht UTC teruggezet. GET /api/v1/account toont wat er vandaag nog over is.

WatPer dagPer aanroep
Vrijgegeven mensen, via filters100 (geen limiet op een plan)25
Exportrijen50.000 (geen limiet op een plan)50.000 per bestand, 500.000 per batch
Zoekopdrachten in de e-mailfinder2.00030 per minuut, lijsten tot 10.000 rijen

Een account zonder plan vindt bovendien maximaal 10 nieuwe e-mailadressen per dag in totaal: vrijgaven, resultaten van de e-mailfinder en exportrijen tellen samen, en een e-mailadres dat het account al had, telt niet mee.

Boven een daglimiet krijg je 429 daily_limit_reached. Wil je meer mensen dan de daglimiet voor vrijgeven, sla dan een lijst op, exporteer die of voeg die toe aan een campagne; die routes zijn gemaakt voor duizenden mensen. De e-mailfinder antwoordt met eigen codes: finder_rate_limit (per minuut), finder_daily_limit (per dag) en finder_miss_rate_throttle (de meeste zoekopdrachten vonden niets).

Pagina's

Elke lijst neemt limit en cursor aan. De response houdt zijn eigen sleutel (bijvoorbeeld campaigns of people) en voegt total, limit, offset, next_cursor en has_more toe. Geef next_cursor mee als cursor om de volgende pagina te krijgen; op de laatste pagina is die null. offset werkt ook, als je de rijen liever zelf telt.

Sommige lijsten stoppen eerder of bladeren op hun eigen manier. Door de mensen in een campagne blader je met after ingesteld op next_after, in een vaste volgorde, en die pagina's hebben geen next_cursor. Campagneantwoorden bladeren op dezelfde manier met after en next_after. De campagnelijst reikt tot de eerste 500 campagnes; cursor bladert binnen die campagnes. De inbox, campagneantwoorden en de mensen in een campagne nemen ook een datumfilter aan (updated_after en received_after, of created_after) in 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"

Als total_is_estimate true is, is total het minimum dat er is, bijvoorbeeld als een lijst haar maximale grootte heeft bereikt.

Veilige herhalingen

Stuur een header Idempotency-Key mee met elke schrijfaanroep: aanmaken, wijzigen, verwijderen, beantwoorden, doorsturen en alles wat credits of geld kost. Gebruik een nieuwe willekeurige waarde voor elke nieuwe actie en dezelfde waarde als je die actie opnieuw probeert.

  • Dezelfde sleutel met dezelfde body binnen 24 uur geeft de eerste response terug, met de header Idempotent-Replayed: true. Niets wordt twee keer gedaan.
  • Dezelfde sleutel met een andere body geeft 409 idempotency_conflict.
  • Zolang het eerste request nog loopt, geeft een nieuwe poging 409 idempotency_in_progress. Wacht even en probeer het opnieuw.
  • Fouten worden niet opgeslagen, dus je kunt het probleem oplossen en het opnieuw proberen met dezelfde sleutel.
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 die niet kunnen starten

POST /api/v1/campaigns/{id}/launch geeft launch_blocked zolang er iets ontbreekt, bijvoorbeeld een e-mail, een mailbox die vandaag nog ruimte heeft, of mensen. details.blockers noemt elk ervan in gewone woorden. GET /api/v1/campaigns/{id} toont dezelfde lijst als launch_blockers, zodat je ze kunt oplossen voordat je het probeert.

Op deze pagina