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.
{
"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
| Codice | Stato | Cosa significa e cosa fare |
|---|---|---|
invalid_request | 400 | Alla richiesta manca qualcosa o un valore è sbagliato. Il messaggio dice cosa correggere. |
launch_blocked | 400 | La campagna non può ancora essere avviata. details.blockers elenca cosa manca. |
unauthorized | 401 | Nessuna chiave API, oppure la chiave è sbagliata o revocata. |
api_key_required | 401 | Questa route richiede una chiave API o un accesso tramite connettore, non una sessione del browser. |
plan_required | 402 | Il 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_credits | 402 | Crediti insufficienti per questa chiamata. details indica quanti ne servono. Non è stato addebitato nulla. |
scope_missing | 403 | Alla chiave manca uno scope richiesto da questa chiamata. Crea una chiave con quello scope. |
permission_missing | 403 | Il tuo ruolo nel workspace non consente questa azione. |
forbidden | 403 | Questa azione non è consentita per questo account. |
not_found | 404 | Nessun elemento di questo tipo nel tuo workspace. Gli elementi di altri workspace rispondono allo stesso modo. |
route_not_found | 404 | Questo endpoint non esiste. Confronta il percorso con il riferimento. |
method_not_allowed | 405 | Il percorso esiste, ma non con questo metodo HTTP. details.allowed elenca i metodi. |
conflict | 409 | L'elemento è in uno stato che non lo consente, ad esempio quando elimini una campagna in corso. |
idempotency_conflict | 409 | Questo Idempotency-Key è già stato usato con un body diverso. |
idempotency_in_progress | 409 | Una richiesta con questo Idempotency-Key è ancora in corso. Attendi e riprova. |
gone | 410 | L'elemento è scaduto, ad esempio un file di esportazione più vecchio del suo tempo di conservazione. |
quote_expired | 410 | Il preventivo è troppo vecchio. Chiedi un nuovo preventivo e conferma di nuovo. |
validation_error | 422 | Un campo ha il tipo sbagliato o manca. details.fields elenca ogni problema. |
access_key_activation_required | 428 | Questa chiave di accesso ricevuta con un invito non è ancora attiva. Prima conferma l'email in details.claim_url. |
rate_limited | 429 | Troppe 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_reached | 429 | Un 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_error | 500 | Qualcosa non ha funzionato da parte nostra. Riprova; indica il request id se continua a fallire. |
unavailable | 503 | Una parte del servizio è occupata o in pausa. Riprova tra un minuto. |
confirmation_required | 400 | Un ordine richiede confirmed=true, inviato solo dopo che la persona che paga ha detto sì. |
invalid_webhook_url | 400 | L'indirizzo del webhook deve essere un indirizzo pubblico https://. |
invalid_webhook_events | 400 | Il nome di un evento è sconosciuto oppure non è stato indicato nessun evento. details.invalid elenca i nomi sconosciuti. |
webhook_limit_reached | 400 | Hai 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_subscribed | 400 | Una chiamata di test ha indicato un evento che il webhook non riceve. details.events elenca quelli che riceve. |
company_credits_required | 402 | Un profilo aziendale completo costa crediti e l'account ne ha troppo pochi. details.teaser contiene la parte gratuita; non è stato addebitato nulla. |
search_busy | 503 | La ricerca è occupata in questo momento. Riprova tra qualche secondo. |
phones_not_in_plan | 402 | I numeri di telefono sono inclusi dal piano Pro. Non è stato addebitato nulla. |
card_not_charged | 402 | La carta salvata non è stata addebitata. Non è stato acquistato nulla; paga invece tramite un link di pagamento. |
owner_only | 403 | Solo il proprietario del workspace può farlo, ad esempio ordinare o disdire caselle. |
quote_not_found | 404 | Il preventivo non esiste o appartiene a qualcun altro. Chiedi un nuovo preventivo. |
charge_in_progress | 409 | Questo preventivo è in fase di addebito proprio ora. Controlla l'ordine tra poco. |
not_enough_names | 409 | Non sono stati trovati abbastanza nomi di dominio liberi. Invia tu alcuni domini. |
not_paid | 409 | L'ordine non è ancora pagato, quindi non c'è nulla da disdire. |
reason_required | 422 | Per disdire caselle serve un motivo tra le scelte elencate. |
not_connected | 409 | Quello strumento non è ancora collegato. Prima collegalo in Impostazioni, Strumenti collegati. |
unsupported_tool | 409 | Questo strumento collegato non può ricevere persone direttamente. Inviagli invece un'esportazione dalla pagina Esportazioni. |
tool_key_rejected | 409 | Lo strumento collegato non ha accettato la chiave salvata. Collegalo di nuovo in Impostazioni, Strumenti collegati. |
price_mismatch | 409 | Il prezzo che hai mostrato alla persona non è il prezzo del preventivo. Mostra il prezzo del preventivo e chiedi di nuovo. |
quote_other_session | 409 | Il preventivo è stato fatto con un'altra chiave o un altro collegamento. Chiedi qui un nuovo preventivo e conferma di nuovo. |
export_failed | 409 | L'esportazione non è terminata, quindi non c'è nulla da inviare. Esegui di nuovo l'esportazione. |
sign_in_failed | 422 | Il 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_started | 409 | La campagna è una bozza, quindi non c'è nulla da mettere in pausa. Prima avviala. |
finder_rate_limit | 429 | Più di 30 ricerche email singole in questo minuto. Attendi Retry-After secondi. |
finder_daily_limit | 429 | 2.000 ricerche email oggi. Si azzera a mezzanotte UTC. |
finder_miss_rate_throttle | 429 | La 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.
| Piano | Richieste al minuto | In 10 secondi |
|---|---|---|
| Senza piano, chiave API o CLI | 30 | 15 |
| Senza piano, assistente AI | 60 | 20 |
| Starter | 60 | 15 |
| Pro | 240 | 60 |
| Scale | 600 | 150 |
| Hyperscale | 1.200 | 300 |
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.
| Piano | Al minuto | Conteggi al giorno | Righe di anteprima al giorno |
|---|---|---|---|
| Senza piano, chiave API o CLI | 10 | 500 | 500 |
| Senza piano, assistente AI | 20 | 1.000 | 1.000 |
| Starter | 30 | nessun limite | nessun limite |
| Pro | 60 | nessun limite | nessun limite |
| Scale | 90 | nessun limite | nessun limite |
| Hyperscale | 120 | nessun limite | nessun 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.
| Cosa | Al giorno | Per chiamata |
|---|---|---|
| Persone sbloccate, tramite filtri | 100 (nessun limite su un piano) | 25 |
| Righe di esportazione | 50.000 (nessun limite su un piano) | 50.000 per file, 500.000 per lotto |
| Ricerche email | 2.000 | 30 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.
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.
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.
Autenticazione
Chiavi API, l'URL di base, cosa consente ogni scope di una chiave e come gli agenti AI accedono senza chiave.
Guide
Guide passo dopo passo per i lavori che si fanno più spesso con Argorant: la prima chiamata, trovare persone e scrivere loro, le risposte, i crediti, le caselle e i webhook.