Conceitos básicos

Erros

O Gemlead retorna um status HTTP e um erro em JSON cujos type e code nunca mudam, para que o seu código possa tratar cada caso com base neles.

O objeto de erro

Todo erro tem o mesmo formato. message é para pessoas e pode mudar, type e code são para o seu código. Toda resposta, com erro ou não, também traz o cabeçalho Request-Id.

Atributos

typestring
A família do erro, uma por status HTTP.
codestring
O que deu errado exatamente. Veja os códigos abaixo.
messagestring
Uma frase que explica o erro.
paramstring ou null
O parâmetro com problema, quando há um.
request_idstring
O ID da requisição, o mesmo do cabeçalho Request-Id. Envie esse ID para a gente quando precisar de ajuda.
doc_urlstring
Esta página, aberta na entrada do código.

Resposta400

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

Códigos de status HTTP

Status	Tipo	Significado
400	`invalid_request_error`	A requisição tem um parâmetro ausente, desconhecido ou inválido. Um método que o caminho não aceita também recebe este tipo, com um 405.
401	`authentication_error`	Sem chave, chave errada ou chave revogada.
403	`permission_error`	A chave é válida, mas não pode fazer isso, como uma chave `read` tentando escrever, ou uma conta no plano Free ou Starter.
404	`not_found_error`	Esse objeto não existe na conta da chave, ou essa rota não existe.
409	`idempotency_error`	Uma `Idempotency-Key` foi reutilizada em outra requisição, ou a primeira requisição com ela ainda está em execução.
429	`rate_limit_error`	Requisições demais. Espere `Retry-After` segundos.
500	`api_error`	Algo deu errado do nosso lado, ou 501 para um endpoint que ainda não está disponível. Tente de novo mais tarde com a mesma `Idempotency-Key`.

Códigos de erro

Código	Status	Significado
`api_key_missing`	401	A requisição não tem o cabeçalho `Authorization` nem o `X-Api-Key`.
`api_key_invalid`	401	Nenhuma chave corresponde. Confira se você copiou a chave inteira, com `gl_live_`.
`api_key_revoked`	401	A chave foi revogada no app. Crie uma nova.
`token_expired`	401	Um access token OAuth de um assistente de IA expirou. O assistente renova o token sozinho.
`insufficient_scope`	403	A chave tem o scope `read` e a requisição altera dados. Use uma chave com `write`.
`plan_required`	403	O dono da conta está no plano Free ou Starter. A API funciona no Business e no Enterprise, também durante o teste grátis, e a mesma chave volta a funcionar quando a conta passa para um deles.
`forbidden`	403	O usuário da chave não tem permissão para isso nesta conta do X, como um membro que altera a equipe sem ser admin ou que compartilha uma persona.
`parameter_missing`	400	Falta um parâmetro obrigatório. `param` diz qual.
`parameter_invalid`	400	Um parâmetro tem um valor que a API não aceita, como um score acima de 100 ou uma data fora do ISO 8601. `param` diz qual.
`parameter_unknown`	400	A query string ou o corpo tem um parâmetro que este endpoint não aceita. `param` diz qual.
`body_invalid`	400	O corpo não é um JSON válido, ou não é um objeto JSON.
`cursor_invalid`	400	O `cursor` não foi gerado pela API ou foi criado para outros filtros.
`idempotency_key_invalid`	400	A `Idempotency-Key` tem mais de 255 caracteres.
`method_not_allowed`	405	Este caminho não aceita este método. O cabeçalho `Allow` lista os métodos aceitos.
`url_invalid`	400	Uma URL de webhook não é HTTPS, contém credenciais, não resolve ou aponta para um endereço privado.
`webhook_endpoint_limit_reached`	400	A conta já tem 10 endpoints de webhook. Exclua um antes.
`resource_already_exists`	400	Isso já existe, como uma fonte que a persona já usa com este método ou uma busca por palavra-chave que ela já tem.
`limit_reached`	400	Um limite foi atingido, como 100 personas numa conta, 500 buscas por palavra-chave numa persona ou 50 colunas no quadro.
`seed_source_refused`	400	Uma fonte inicial de uma nova persona foi recusada, como um investidor, uma aceleradora ou uma conta de mídia. Essas contas não trazem compradores.
`x_profile_not_found`	400	O X não tem um perfil que possa ser lido com este username.
`lead_without_x_id`	400	O lead ainda não tem ID de conta do X, então não pode ser seguido.
`lead_not_convertible`	400	O lead não pertence a nenhuma persona, então não pode virar fonte.
`campaign_archived`	400	A campanha está arquivada. Duplique-a para rodá-la de novo.
`campaign_not_started`	400	A campanha é um rascunho, então não há nada para pausar.
`campaign_flow_empty`	400	O fluxo da campanha ainda não tem etapas. Adicione uma antes de iniciá-la.
`column_protected`	400	Esta coluna é do próprio quadro, como a Caixa de entrada ou uma coluna de persona, e não pode ser excluída.
`shared_account_has_campaigns`	400	Uma conta do X que você está tirando de uma persona compartilhada ainda tem campanhas nela. Exclua as campanhas e tente de novo.
`owner_cannot_leave`	400	O dono de uma conta do X não pode sair da equipe dela. Remova os membros em vez disso.
`translation_off`	400	A tradução da conversa está desativada. Ative a tradução ou traduza uma mensagem por vez.
`recipient_not_messageable`	400	O X recusou a DM. O lead fechou as DMs ou bloqueou a conta.
`media_kind_unsupported`	400	A conversa não aceita este tipo de arquivo. Uma mensagem de voz precisa de uma conversa do X Chat.
`x_session_expired`	409	A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.
`assistant_busy`	409	O Julien AI ainda está respondendo a uma mensagem deste chat, ou a 3 mensagens desta conta do X. Espere essa resposta e envie de novo.
`conversation_unavailable`	409	A conversa ainda não tem um usuário do X para quem escrever.
`resource_missing`	404	Nenhum objeto com este ID na conta da chave. Um ID de outra conta recebe a mesma resposta.
`route_not_found`	404	Nenhum endpoint neste caminho.
`idempotency_key_reused`	409	Esta `Idempotency-Key` foi usada nas últimas 24 horas com outro método, caminho ou corpo.
`idempotency_key_in_use`	409	A primeira requisição com esta `Idempotency-Key` ainda está em execução. Tente de novo em um segundo.
`rate_limit_exceeded`	429	Mais de 120 requisições no minuto com esta chave. Espere `Retry-After` segundos.
`export_rate_limit_exceeded`	429	Mais de 10 exportações na mesma hora nesta conta.
`dm_paused`	429	O X está limitando as DMs da conta por enquanto. `Retry-After` diz quando elas voltam.
`dm_rate_limited`	429	Mais de 10 DMs no minuto a partir desta conta.
`dm_daily_limit`	429	300 DMs hoje em UTC a partir desta conta, ou a cota diária que o próprio X definiu para ela.
`assistant_rate_limited`	429	Mais de 6 mensagens ao Julien AI no minuto a partir desta conta do X, ou 150 na hora para o dono dela, incluindo o chat do app.
`assistant_daily_limit`	429	100 mensagens ao Julien AI hoje em UTC a partir desta conta do X.
`passcode_rate_limited`	429	Mais de 5 tentativas do código do X Chat na mesma hora nesta conta. O X conta cada tentativa.
`internal_error`	500	Um erro inesperado do nosso lado. O `request_id` ajuda a gente a encontrar o problema.
`request_timeout`	500	A requisição demorou demais. Tente de novo, com a mesma `Idempotency-Key` se ela alterar dados.
`not_implemented`	501	Este endpoint ainda não está disponível.
`upstream_unavailable`	502	O X ou um serviço do Gemlead não respondeu. Nada mudou, tente de novo em um minuto.

Tratar erros

400, 401, 403 e 404 nunca funcionam sem alterações. Corrija a requisição antes de enviá-la de novo.
409 com idempotency_key_in_use funciona um segundo depois. Tente de novo com a mesma Idempotency-Key.
429 funciona depois de Retry-After segundos. Veja Limites de uso.
500 pode ser repetido após uma breve espera. Envie a mesma Idempotency-Key nas requisições que alteram dados, para que nada seja executado duas vezes.
Registre o request_id de cada erro. Com ele, a gente encontra a requisição em segundos.