ArgorantDocs

Errori e limiti

L'unica forma degli errori, ogni codice di errore, il request id, i limiti di richieste per piano, i limiti su ricerche e conteggi, i limiti giornalieri, le pagine e i nuovi tentativi sicuri.

Un'unica forma degli errori

Ogni risposta di errore ha lo stesso aspetto. Leggi error.code per decidere cosa fare e mostra error.message alle persone. Il messaggio è una frase semplice.

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 contiene la forma precedente dell'errore per i client scritti prima di questa forma. Il codice nuovo dovrebbe leggere error.

Codici di errore

CodiceStatoCosa significa e cosa fare
invalid_request400Alla richiesta manca qualcosa o un valore è sbagliato. Il messaggio dice cosa correggere.
launch_blocked400La campagna non può ancora essere avviata. details.blockers elenca cosa manca.
unauthorized401Nessuna chiave API, oppure la chiave è sbagliata o revocata.
api_key_required401Questa route richiede una chiave API o un accesso tramite connettore, non una sessione del browser.
plan_required402Il piano dell'account non include questa funzione. Il messaggio indica il piano che la include. La chiave di un account senza piano e senza crediti lo riceve a ogni chiamata.
insufficient_credits402Crediti insufficienti per questa chiamata. details indica quanti ne servono. Non è stato addebitato nulla.
scope_missing403Alla chiave manca uno scope richiesto da questa chiamata. Crea una chiave con quello scope.
permission_missing403Il tuo ruolo nel workspace non consente questa azione.
forbidden403Questa azione non è consentita per questo account.
not_found404Nessun elemento di questo tipo nel tuo workspace. Gli elementi di altri workspace rispondono allo stesso modo.
route_not_found404Questo endpoint non esiste. Confronta il percorso con il riferimento.
method_not_allowed405Il percorso esiste, ma non con questo metodo HTTP. details.allowed elenca i metodi.
conflict409L'elemento è in uno stato che non lo consente, ad esempio quando elimini una campagna in corso.
idempotency_conflict409Questo Idempotency-Key è già stato usato con un body diverso.
idempotency_in_progress409Una richiesta con questo Idempotency-Key è ancora in corso. Attendi e riprova.
gone410L'elemento è scaduto, ad esempio un file di esportazione più vecchio del suo tempo di conservazione.
quote_expired410Il preventivo è troppo vecchio. Chiedi un nuovo preventivo e conferma di nuovo.
validation_error422Un campo ha il tipo sbagliato o manca. details.fields elenca ogni problema.
access_key_activation_required428Questa chiave di accesso ricevuta con un invito non è ancora attiva. Prima conferma l'email in details.claim_url.
rate_limited429Troppe richieste in questo minuto o in 10 secondi, troppe ricerche e conteggi in questo minuto, oppure più di 200 persone sbloccate in un minuto. Attendi Retry-After secondi.
daily_limit_reached429Un limite giornaliero è esaurito: il limite della chiave per questo tipo di chiamata, oppure le nuove email al giorno di un account senza piano. details.action lo indica. Si azzera a mezzanotte UTC.
internal_error500Qualcosa non ha funzionato da parte nostra. Riprova; indica il request id se continua a fallire.
unavailable503Una parte del servizio è occupata o in pausa. Riprova tra un minuto.
confirmation_required400Un ordine richiede confirmed=true, inviato solo dopo che la persona che paga ha detto sì.
invalid_webhook_url400L'indirizzo del webhook deve essere un indirizzo pubblico https://.
invalid_webhook_events400Il nome di un evento è sconosciuto oppure non è stato indicato nessun evento. details.invalid elenca i nomi sconosciuti.
webhook_limit_reached400Hai 10 webhook attivi, oppure 50 in totale contando quelli disattivati. Prima eliminane uno o disattivane uno. Ogni membro del team ha i propri.
event_not_subscribed400Una chiamata di test ha indicato un evento che il webhook non riceve. details.events elenca quelli che riceve.
company_credits_required402Un profilo aziendale completo costa crediti e l'account ne ha troppo pochi. details.teaser contiene la parte gratuita; non è stato addebitato nulla.
search_busy503La ricerca è occupata in questo momento. Riprova tra qualche secondo.
phones_not_in_plan402I numeri di telefono sono inclusi dal piano Pro. Non è stato addebitato nulla.
card_not_charged402La carta salvata non è stata addebitata. Non è stato acquistato nulla; paga invece tramite un link di pagamento.
owner_only403Solo il proprietario del workspace può farlo, ad esempio ordinare o disdire caselle.
quote_not_found404Il preventivo non esiste o appartiene a qualcun altro. Chiedi un nuovo preventivo.
charge_in_progress409Questo preventivo è in fase di addebito proprio ora. Controlla l'ordine tra poco.
not_enough_names409Non sono stati trovati abbastanza nomi di dominio liberi. Invia tu alcuni domini.
not_paid409L'ordine non è ancora pagato, quindi non c'è nulla da disdire.
reason_required422Per disdire caselle serve un motivo tra le scelte elencate.
not_connected409Quello strumento non è ancora collegato. Prima collegalo in Impostazioni, Strumenti collegati.
unsupported_tool409Questo strumento collegato non può ricevere persone direttamente. Inviagli invece un'esportazione dalla pagina Esportazioni.
tool_key_rejected409Lo strumento collegato non ha accettato la chiave salvata. Collegalo di nuovo in Impostazioni, Strumenti collegati.
price_mismatch409Il prezzo che hai mostrato alla persona non è il prezzo del preventivo. Mostra il prezzo del preventivo e chiedi di nuovo.
quote_other_session409Il preventivo è stato fatto con un'altra chiave o un altro collegamento. Chiedi qui un nuovo preventivo e conferma di nuovo.
export_failed409L'esportazione non è terminata, quindi non c'è nulla da inviare. Esegui di nuovo l'esportazione.
sign_in_failed422Il server di posta non ha accettato l'accesso, quindi la casella non è stata collegata. details.test indica, per l'invio e per la lettura delle risposte, cosa non ha funzionato.
campaign_not_started409La campagna è una bozza, quindi non c'è nulla da mettere in pausa. Prima avviala.
finder_rate_limit429Più di 30 ricerche email singole in questo minuto. Attendi Retry-After secondi.
finder_daily_limit4292.000 ricerche email oggi. Si azzera a mezzanotte UTC.
finder_miss_rate_throttle429La maggior parte delle ricerche recenti non ha trovato nulla, quindi per un po' le ricerche sono rallentate a 20 all'ora. Controlla i nomi e i domini.

Alcune operazioni aggiungono un codice proprio, come confirmation_required o quote_not_found. Ogni operazione elenca i suoi codici nel riferimento. Tratta un codice che non conosci in base al suo stato HTTP.

Il request id

Ogni risposta contiene un header X-Request-Id, e ogni errore lo ripete come request_id. Invia un tuo id nell'header X-Request-Id (da 8 a 64 lettere, cifre, punti, trattini o trattini bassi) per ritrovare una chiamata nei tuoi log. Indica l'id quando chiedi aiuto.

Richieste al minuto

Ogni chiave può inviare questo numero di richieste al minuto, e fino al secondo numero in 10 secondi qualsiasi.

PianoRichieste al minutoIn 10 secondi
Senza piano, chiave API o CLI3015
Senza piano, assistente AI6020
Starter6015
Pro24060
Scale600150
Hyperscale1.200300

Senza piano comprende i primi 7 giorni di un account che non ha ancora scelto un piano e gli account che usano crediti acquistati in precedenza. La prova di un piano ha i limiti di quel piano. La chiave di un account senza piano e senza crediti riceve 402 plan_required a ogni chiamata, compresa GET /api/v1/account.

Ogni risposta a una chiamata con chiave contiene X-RateLimit-Limit (richieste al minuto), X-RateLimit-Remaining (richieste rimaste in questo minuto) e X-RateLimit-Reset (secondi prima che il minuto ricominci). Oltre uno dei due limiti ricevi 429 rate_limited con un header Retry-After. Attendi quel numero di secondi, poi riprova.

Sbloccare persone ha un limite in più su ogni piano: un account sblocca fino a 200 persone al minuto. Oltre questo limite ricevi anche in questo caso 429 rate_limited.

Ricerche e conteggi

Ricerche, conteggi e anteprime sono gratuiti. Sono limitati per account, su tutte le sue chiavi e il connettore, quindi una seconda chiave non aggiunge altro.

PianoAl minutoConteggi al giornoRighe di anteprima al giorno
Senza piano, chiave API o CLI10500500
Senza piano, assistente AI201.0001.000
Starter30nessun limitenessun limite
Pro60nessun limitenessun limite
Scale90nessun limitenessun limite
Hyperscale120nessun limitenessun limite

Senza piano, ricerche e conteggi contengono anche X-RateLimit-Daily-Limit e X-RateLimit-Daily-Remaining. Un'anteprima contiene fino a 10 persone per chiamata.

Limiti giornalieri per chiave

Senza piano, ogni chiave ha anche limiti giornalieri. Su un piano ne ha uno solo la ricerca email; il resto è limitato dai crediti. I limiti giornalieri si azzerano a mezzanotte UTC. GET /api/v1/account mostra cosa resta per oggi.

CosaAl giornoPer chiamata
Persone sbloccate, tramite filtri100 (nessun limite su un piano)25
Righe di esportazione50.000 (nessun limite su un piano)50.000 per file, 500.000 per lotto
Ricerche email2.00030 al minuto, liste fino a 10.000 righe

Un account senza piano trova anche fino a 10 nuove email al giorno in totale: sblocchi, risultati della ricerca email e righe di esportazione contano insieme, e un'email che l'account aveva già non conta.

Oltre un limite giornaliero ricevi 429 daily_limit_reached. Per più persone del limite giornaliero di sblocco, salva una lista, esportala o aggiungila a una campagna; queste strade sono fatte per migliaia di persone. La ricerca email risponde con codici propri: finder_rate_limit (al minuto), finder_daily_limit (al giorno) e finder_miss_rate_throttle (la maggior parte delle ricerche non ha trovato nulla).

Pagine

Ogni lista accetta limit e cursor. La risposta mantiene la propria chiave (ad esempio campaigns o people) e aggiunge total, limit, offset, next_cursor e has_more. Passa next_cursor come cursor per ottenere la pagina successiva; nell'ultima pagina è null. Funziona anche offset, se preferisci contare le righe da solo.

Alcune liste finiscono prima o vanno a pagine a modo loro. Le persone di una campagna vanno a pagine con after impostato su next_after, in un ordine fisso, e quelle pagine non contengono next_cursor. Le risposte di una campagna vanno a pagine allo stesso modo con after e next_after. La lista delle campagne arriva alle prime 500 campagne; cursor scorre le pagine al loro interno. La posta in arrivo, le risposte di una campagna e le persone di una campagna accettano anche un filtro per data (updated_after e received_after, oppure 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"

Quando total_is_estimate è true, total è il valore minimo, ad esempio quando una lista ha raggiunto la sua dimensione massima.

Nuovi tentativi sicuri

Invia un header Idempotency-Key con ogni scrittura: creazione, modifica, eliminazione, risposta, inoltro e qualsiasi cosa che spenda crediti o denaro. Usa un nuovo valore casuale per ogni nuova azione e lo stesso valore quando la ritenti.

  • La stessa chiave con lo stesso body entro 24 ore restituisce la prima risposta, con l'header Idempotent-Replayed: true. Nulla viene eseguito due volte.
  • La stessa chiave con un body diverso risponde 409 idempotency_conflict.
  • Mentre la prima richiesta è ancora in corso, un nuovo tentativo risponde 409 idempotency_in_progress. Attendi un momento e riprova.
  • Gli errori non vengono salvati, quindi puoi correggere il problema e ritentare con la stessa chiave.
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}'

Campagne che non possono essere avviate

POST /api/v1/campaigns/{id}/launch risponde launch_blocked finché manca qualcosa, ad esempio un'email, una casella con spazio rimasto per oggi, oppure persone. details.blockers elenca ciascun elemento in parole semplici. GET /api/v1/campaigns/{id} mostra la stessa lista come launch_blockers, così puoi risolvere tutto prima di provare.

In questa pagina