Concetti di base

Errori

Gemlead risponde con uno stato HTTP e un errore JSON i cui type e code non cambiano mai, così il tuo codice può decidere in base a questi valori.

L'oggetto errore

Ogni errore ha la stessa forma. message è pensato per le persone e può cambiare, type e code sono per il tuo codice. Ogni risposta, di errore o no, include anche l'header Request-Id.

Attributi

typestring
La famiglia dell'errore, una per ogni stato HTTP.
codestring
Cosa è andato storto, nel dettaglio. Vedi i codici qui sotto.
messagestring
Una frase che spiega l'errore.
paramstring o null
Il parametro che causa l'errore, se c'è.
request_idstring
L'ID della richiesta, uguale al suo header Request-Id. Inviacelo quando ti serve aiuto.
doc_urlstring
Questa pagina, alla voce del codice.

Risposta400

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "score_min must be an integer from 0 to 100.",
    "param": "score_min",
    "request_id": "req_7Hq2LmX9pT4vK1sN",
    "doc_url": "https://gemlead.ai/docs/errors#parameter_invalid"
  }
}

Codici di stato HTTP

Stato	Tipo	Significato
400	`invalid_request_error`	Nella richiesta un parametro manca, è sconosciuto o non è valido. Anche un metodo che il path non accetta riceve questo tipo, con un 405.
401	`authentication_error`	Nessuna chiave, una chiave sbagliata o una chiave revocata.
403	`permission_error`	La chiave è valida ma non può fare questa operazione, come una chiave `read` che prova a scrivere o un account sul piano Free o Starter.
404	`not_found_error`	L'oggetto non esiste sull'account della chiave, oppure la route non esiste.
409	`idempotency_error`	Una `Idempotency-Key` è stata riusata per un'altra richiesta, oppure la sua prima richiesta è ancora in corso.
429	`rate_limit_error`	Troppe richieste. Attendi `Retry-After` secondi.
500	`api_error`	Qualcosa è andato storto da parte nostra, oppure 501 per un endpoint non ancora disponibile. Riprova più tardi con la stessa `Idempotency-Key`.

Codici di errore

Codice	Stato	Significato
`api_key_missing`	401	La richiesta non ha l'header `Authorization` né `X-Api-Key`.
`api_key_invalid`	401	Nessuna chiave corrisponde. Verifica di averla copiata tutta, `gl_live_` compreso.
`api_key_revoked`	401	La chiave è stata revocata nell'app. Creane una nuova.
`token_expired`	401	Il token di accesso OAuth di un assistente IA è scaduto. L'assistente lo rinnova da solo.
`insufficient_scope`	403	La chiave ha lo scope `read` e la richiesta modifica i dati. Usa una chiave con `write`.
`plan_required`	403	Il proprietario dell'account è sul piano Free o Starter. L'API funziona su Business ed Enterprise, prova compresa, e la stessa chiave torna a funzionare appena l'account passa a uno dei due.
`forbidden`	403	L'utente della chiave non può farlo su questo account X, come un membro che modifica il team senza essere admin o che condivide una buyer persona.
`parameter_missing`	400	Manca un parametro obbligatorio. `param` lo indica.
`parameter_invalid`	400	Un parametro ha un valore che l'API non accetta, come un punteggio sopra 100 o una data non in ISO 8601. `param` lo indica.
`parameter_unknown`	400	La query o il body contiene un parametro che questo endpoint non accetta. `param` lo indica.
`body_invalid`	400	Il body non è JSON valido, oppure non è un oggetto JSON.
`cursor_invalid`	400	Il `cursor` non è uno di quelli forniti dall'API, oppure è stato creato per altri filtri.
`idempotency_key_invalid`	400	La `Idempotency-Key` supera i 255 caratteri.
`method_not_allowed`	405	Questo path non accetta questo metodo. L'header `Allow` elenca quelli che accetta.
`url_invalid`	400	Un URL di webhook non è HTTPS, contiene credenziali, non si risolve o punta a un indirizzo privato.
`webhook_endpoint_limit_reached`	400	L'account ha già 10 endpoint webhook. Eliminane prima uno.
`resource_already_exists`	400	Esiste già, come una fonte che la buyer persona ha già con questo metodo o una ricerca per parola chiave che ha già.
`limit_reached`	400	È stato raggiunto un limite, come 100 buyer persona per account, 500 ricerche per parola chiave per buyer persona o 50 colonne nella board.
`seed_source_refused`	400	Una fonte di partenza di una nuova buyer persona viene rifiutata, come un investitore, un acceleratore o un account media. Non portano acquirenti.
`x_profile_not_found`	400	Su X non esiste un profilo leggibile con questo username.
`lead_without_x_id`	400	Il lead non ha ancora un ID account X, quindi non si può seguire.
`lead_not_convertible`	400	Il lead non appartiene a nessuna buyer persona, quindi non può diventare una fonte.
`campaign_archived`	400	La campagna è archiviata. Duplicala per farla ripartire.
`campaign_not_started`	400	La campagna è una bozza, quindi non c'è nulla da mettere in pausa.
`campaign_flow_empty`	400	Il flusso della campagna non ha ancora nessun passaggio. Aggiungine uno prima di avviarla.
`column_protected`	400	Questa colonna fa parte della board, come Posta in arrivo o la colonna di una buyer persona, e non si può eliminare.
`shared_account_has_campaigns`	400	Un account X che togli da una buyer persona condivisa ha ancora campagne su di essa. Eliminale, poi riprova.
`owner_cannot_leave`	400	Il proprietario di un account X non può lasciare il suo team. Può invece rimuovere i membri.
`translation_off`	400	La traduzione della conversazione è disattivata. Attivala, oppure traduci un messaggio alla volta.
`recipient_not_messageable`	400	X ha rifiutato il DM. Il lead ha chiuso i DM o ha bloccato l'account.
`media_kind_unsupported`	400	La conversazione non accetta questo tipo di file. Un messaggio vocale richiede una conversazione X Chat.
`x_session_expired`	409	La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.
`assistant_busy`	409	Julien AI sta ancora rispondendo a un messaggio di questa chat, o a 3 messaggi di questo account X. Attendi quella risposta, poi invia di nuovo.
`conversation_unavailable`	409	La conversazione non ha ancora un utente X a cui scrivere.
`resource_missing`	404	Nessun oggetto con questo ID sull'account della chiave. Un ID di un altro account riceve la stessa risposta.
`route_not_found`	404	Nessun endpoint su questo path.
`idempotency_key_reused`	409	Questa `Idempotency-Key` è stata usata nelle ultime 24 ore per un metodo, un path o un body diversi.
`idempotency_key_in_use`	409	La prima richiesta con questa `Idempotency-Key` è ancora in corso. Riprova tra un secondo.
`rate_limit_exceeded`	429	Più di 120 richieste in un minuto con questa chiave. Attendi `Retry-After` secondi.
`export_rate_limit_exceeded`	429	Più di 10 export in un'ora su questo account.
`dm_paused`	429	Per ora X limita i DM dell'account. `Retry-After` indica quando ripartono.
`dm_rate_limited`	429	Più di 10 DM in un minuto da questo account.
`dm_daily_limit`	429	300 DM oggi, in UTC, da questo account, oppure la quota giornaliera che X gli assegna.
`assistant_rate_limited`	429	Più di 6 messaggi a Julien AI in un minuto da questo account X, o 150 in un'ora per il suo proprietario, chat dell'app compresa.
`assistant_daily_limit`	429	100 messaggi a Julien AI oggi, in UTC, da questo account X.
`passcode_rate_limited`	429	Più di 5 tentativi del codice X Chat in un'ora su questo account. X conta ogni tentativo.
`internal_error`	500	Un errore imprevisto da parte nostra. Il `request_id` ci aiuta a trovarlo.
`request_timeout`	500	La richiesta ha impiegato troppo tempo. Riprovala, con la stessa `Idempotency-Key` se modifica i dati.
`not_implemented`	501	Questo endpoint non è ancora disponibile.
`upstream_unavailable`	502	X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra un minuto.

Gestisci gli errori

400, 401, 403 e 404 non vanno mai a buon fine così come sono. Correggi la richiesta prima di inviarla di nuovo.
409 con idempotency_key_in_use va a buon fine un secondo dopo. Riprova con la stessa Idempotency-Key.
429 va a buon fine dopo Retry-After secondi. Vedi Rate limit.
500 si può riprovare dopo una breve attesa. Invia la stessa Idempotency-Key per le richieste che modificano i dati, così nulla viene eseguito due volte.
Salva nei log il request_id di ogni errore. Ci permette di trovare la richiesta in pochi secondi.