Concepts clés

Erreurs

Gemlead répond avec un statut HTTP et une erreur JSON dont le type et le code ne changent jamais, pour que ton code puisse s'appuyer dessus.

L'objet erreur

Toutes les erreurs ont la même forme. message s'adresse aux humains et peut changer, type et code s'adressent à ton code. Chaque réponse, erreur ou non, porte aussi son header Request-Id.

Attributs

typestring
La famille de l'erreur, une par statut HTTP.
codestring
Ce qui a échoué, précisément. Voir les codes ci-dessous.
messagestring
Une phrase qui explique l'erreur.
paramstring ou null
Le paramètre en cause, s'il y en a un.
request_idstring
L'ID de la requête, le même que son header Request-Id. Envoie-le-nous si tu as besoin d'aide.
doc_urlstring
Le lien vers l'entrée de ce code sur cette page.

Réponse400

{
  "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"
  }
}

Codes de statut HTTP

Statut	Type	Signification
400	`invalid_request_error`	La requête a un paramètre manquant, inconnu ou invalide. Une méthode que le chemin n'accepte pas reçoit aussi ce type, avec un 405.
401	`authentication_error`	Pas de clé, une clé incorrecte ou une clé révoquée.
403	`permission_error`	La clé est valide mais n'a pas ce droit, comme une clé `read` qui essaie d'écrire, ou un compte sur le plan Free ou Starter.
404	`not_found_error`	Cet objet n'existe pas sur le compte de la clé, ou cette route n'existe pas.
409	`idempotency_error`	Une `Idempotency-Key` a été réutilisée pour une autre requête, ou sa première requête tourne encore.
429	`rate_limit_error`	Trop de requêtes. Attends `Retry-After` secondes.
500	`api_error`	Une erreur de notre côté, ou 501 pour un endpoint pas encore disponible. Réessaie plus tard avec la même `Idempotency-Key`.

Codes d'erreur

Code	Statut	Signification
`api_key_missing`	401	La requête n'a ni header `Authorization` ni header `X-Api-Key`.
`api_key_invalid`	401	Aucune clé ne correspond. Vérifie que tu l'as copiée en entier, `gl_live_` compris.
`api_key_revoked`	401	La clé a été révoquée dans l'app. Crées-en une nouvelle.
`token_expired`	401	Le token d'accès OAuth d'un assistant IA a expiré. L'assistant le renouvelle tout seul.
`insufficient_scope`	403	La clé a le scope `read` et la requête modifie des données. Utilise une clé avec `write`.
`plan_required`	403	Le propriétaire du compte est sur le plan Free ou Starter. L'API est incluse dans les plans Business et Enterprise, essai compris, et la même clé fonctionne à nouveau dès que le compte passe sur l'un des deux.
`forbidden`	403	L'utilisateur de la clé n'a pas le droit de faire ça sur ce compte X, comme un membre qui modifie l'équipe sans être admin, ou qui partage un persona.
`parameter_missing`	400	Il manque un paramètre obligatoire. `param` indique lequel.
`parameter_invalid`	400	Un paramètre a une valeur que l'API n'accepte pas, comme un score au-dessus de 100 ou une date qui n'est pas en ISO 8601. `param` indique lequel.
`parameter_unknown`	400	La query string ou le corps contient un paramètre que cet endpoint n'accepte pas. `param` indique lequel.
`body_invalid`	400	Le corps n'est pas du JSON valide, ou pas un objet JSON.
`cursor_invalid`	400	Le `cursor` ne vient pas de l'API, ou a été créé pour d'autres filtres.
`idempotency_key_invalid`	400	L'`Idempotency-Key` dépasse 255 caractères.
`method_not_allowed`	405	Ce chemin n'accepte pas cette méthode. Le header `Allow` liste celles qu'il accepte.
`url_invalid`	400	Une URL de webhook n'est pas en HTTPS, contient des identifiants, ne se résout pas ou pointe vers une adresse privée.
`webhook_endpoint_limit_reached`	400	Le compte a déjà 10 endpoints webhook. Supprimes-en un d'abord.
`resource_already_exists`	400	L'élément existe déjà, comme une source que le persona a avec cette méthode, ou une recherche par mots-clés qu'il possède.
`limit_reached`	400	Une limite est atteinte, comme 100 personas sur un compte, 500 recherches par mots-clés sur un persona ou 50 colonnes dans le tableau.
`seed_source_refused`	400	Une source de départ d'un nouveau persona est refusée, comme un investisseur, un accélérateur ou un compte média. Ils n'amènent aucun acheteur.
`x_profile_not_found`	400	X n'a aucun profil lisible pour ce nom d'utilisateur.
`lead_without_x_id`	400	Le lead n'a pas encore d'ID de compte X, il ne peut donc pas être suivi.
`lead_not_convertible`	400	Le lead n'appartient à aucun persona, il ne peut donc pas devenir une source.
`campaign_archived`	400	La campagne est archivée. Duplique-la pour la relancer.
`campaign_not_started`	400	La campagne est un brouillon, il n'y a donc rien à mettre en pause.
`campaign_flow_empty`	400	Le parcours de la campagne n'a encore aucune étape. Ajoutes-en une avant de la lancer.
`column_protected`	400	Cette colonne fait partie du tableau, comme Inbox ou une colonne de persona, et ne peut pas être supprimée.
`shared_account_has_campaigns`	400	Un compte X que tu retires d'un persona partagé a encore des campagnes dessus. Supprime-les, puis réessaie.
`owner_cannot_leave`	400	Le propriétaire d'un compte X ne peut pas quitter son équipe. Il peut en revanche en retirer les membres.
`translation_off`	400	La traduction de la conversation est désactivée. Active-la, ou traduis un message à la fois.
`recipient_not_messageable`	400	X a refusé le DM. Le lead a fermé ses DM ou bloqué le compte.
`media_kind_unsupported`	400	La conversation n'accepte pas ce type de fichier. Un message vocal nécessite une conversation X Chat.
`x_session_expired`	409	La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.
`assistant_busy`	409	Julien AI répond encore à un message de ce chat, ou à 3 messages de ce compte X. Attends cette réponse, puis renvoie ton message.
`conversation_unavailable`	409	La conversation n'a pas encore d'utilisateur X à qui écrire.
`resource_missing`	404	Aucun objet avec cet ID sur le compte de la clé. Un ID d'un autre compte donne la même réponse.
`route_not_found`	404	Aucun endpoint à ce chemin.
`idempotency_key_reused`	409	Cette `Idempotency-Key` a servi dans les dernières 24 heures pour une autre méthode, un autre chemin ou un autre corps.
`idempotency_key_in_use`	409	La première requête avec cette `Idempotency-Key` tourne encore. Réessaie dans une seconde.
`rate_limit_exceeded`	429	Plus de 120 requêtes dans la minute avec cette clé. Attends `Retry-After` secondes.
`export_rate_limit_exceeded`	429	Plus de 10 exports dans l'heure sur ce compte.
`dm_paused`	429	X limite les DM du compte pour le moment. `Retry-After` indique quand ils reprennent.
`dm_rate_limited`	429	Plus de 10 DM dans la minute depuis ce compte.
`dm_daily_limit`	429	Déjà 300 DM depuis ce compte sur la journée UTC en cours, ou le quota journalier que X lui fixe.
`assistant_rate_limited`	429	Plus de 6 messages à Julien AI dans la minute depuis ce compte X, ou 150 dans l'heure pour son propriétaire, chat de l'app compris.
`assistant_daily_limit`	429	Déjà 100 messages à Julien AI depuis ce compte X sur la journée UTC en cours.
`passcode_rate_limited`	429	Plus de 5 essais de code X Chat dans l'heure sur ce compte. X compte chaque essai.
`internal_error`	500	Une erreur inattendue de notre côté. Le `request_id` nous aide à la retrouver.
`request_timeout`	500	La requête a pris trop de temps. Réessaie-la, avec la même `Idempotency-Key` si elle modifie des données.
`not_implemented`	501	Cet endpoint n'est pas encore disponible.
`upstream_unavailable`	502	X ou un service Gemlead n'a pas répondu. Rien n'a changé, réessaie dans une minute.

Gérer les erreurs

400, 401, 403 et 404 ne réussissent jamais en l'état. Corrige la requête avant de la renvoyer.
409 avec idempotency_key_in_use réussit une seconde plus tard. Réessaie avec la même Idempotency-Key.
429 réussit après Retry-After secondes. Voir Limites de requêtes.
En cas de 500, réessaie après une courte attente. Envoie la même Idempotency-Key pour les requêtes qui modifient des données, pour que rien ne soit fait deux fois.
Note le request_id de chaque erreur dans tes logs, il nous permet de retrouver la requête en quelques secondes.