ArgorantDocs

Erros e limites

O formato único de erro, todos os códigos de erro, o ID da requisição, os limites de requisições por plano, os limites de buscas e contagens, os limites diários, as páginas e as novas tentativas seguras.

Um único formato de erro

Toda resposta de erro tem a mesma aparência. Leia error.code para decidir o que fazer e mostre error.message às pessoas. A mensagem é uma frase simples.

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 traz a forma antiga do erro para clientes escritos antes deste formato. Código novo deve ler error.

Códigos de erro

CódigoStatusO que significa e o que fazer
invalid_request400Falta algo na requisição ou um valor está errado. A mensagem diz o que corrigir.
launch_blocked400A campanha ainda não pode ser iniciada. details.blockers lista o que falta.
unauthorized401Nenhuma chave de API, ou a chave está errada ou foi revogada.
api_key_required401Esta rota precisa de uma chave de API ou de um login pelo conector, não de uma sessão do navegador.
plan_required402O plano da conta não inclui isto. A mensagem informa o plano que inclui. A chave de uma conta sem plano e sem créditos recebe este código em toda chamada.
insufficient_credits402Créditos insuficientes para esta chamada. details diz quantos são necessários. Nada foi cobrado.
scope_missing403Falta à chave um escopo de que esta chamada precisa. Crie uma chave com esse escopo.
permission_missing403O seu papel no workspace não permite esta ação.
forbidden403Esta ação não é permitida para esta conta.
not_found404Esse item não existe no seu workspace. Itens de outros workspaces respondem da mesma forma.
route_not_found404Esse endpoint não existe. Confira o caminho na referência.
method_not_allowed405O caminho existe, mas não com este método HTTP. details.allowed lista os métodos.
conflict409O item está em um estado que não permite isto, por exemplo excluir uma campanha em andamento.
idempotency_conflict409Esta Idempotency-Key já foi usada com outro body.
idempotency_in_progress409Uma requisição com esta Idempotency-Key ainda está em andamento. Aguarde e tente de novo.
gone410O item expirou, por exemplo um arquivo de exportação mais antigo que o seu prazo de guarda.
quote_expired410O orçamento é antigo demais. Peça um novo orçamento e confirme de novo.
validation_error422Um campo tem o tipo errado ou está faltando. details.fields lista cada problema.
access_key_activation_required428Esta chave de acesso convidada ainda não está ativa. Confirme primeiro o e-mail em details.claim_url.
rate_limited429Requisições demais neste minuto ou em 10 segundos, buscas e contagens demais neste minuto, ou mais de 200 pessoas reveladas em um minuto. Aguarde Retry-After segundos.
daily_limit_reached429Um limite diário foi esgotado: o limite da chave para este tipo de chamada, ou os novos e-mails por dia de uma conta sem plano. details.action informa qual. Ele é zerado à meia-noite UTC.
internal_error500Algo falhou do nosso lado. Tente de novo; informe o ID da requisição se continuar falhando.
unavailable503Uma parte do serviço está ocupada ou pausada. Tente de novo em um minuto.
confirmation_required400Um pedido precisa de confirmed=true, enviado só depois que a pessoa que paga disse sim.
invalid_webhook_url400O endereço do webhook precisa ser um endereço https:// público.
invalid_webhook_events400Um nome de evento é desconhecido ou nenhum evento foi informado. details.invalid lista os nomes desconhecidos.
webhook_limit_reached400Você tem 10 webhooks ativados, ou 50 no total contando os desativados. Exclua ou desative um primeiro. Cada membro da equipe tem os seus.
event_not_subscribed400Uma chamada de teste informou um evento que o webhook não recebe. details.events lista os que ele recebe.
company_credits_required402Um perfil completo da empresa custa créditos e a conta tem poucos. details.teaser traz a parte grátis; nada foi cobrado.
search_busy503A busca está ocupada agora. Tente de novo em alguns segundos.
phones_not_in_plan402Números de telefone vêm com o plano Pro. Nada foi cobrado.
card_not_charged402O cartão salvo não foi cobrado. Nada foi comprado; pague por um link de pagamento.
owner_only403Só o proprietário do workspace pode fazer isto, por exemplo pedir ou cancelar caixas de e-mail.
quote_not_found404O orçamento não existe ou pertence a outra pessoa. Peça um novo orçamento.
charge_in_progress409Este orçamento está sendo cobrado agora. Confira o pedido daqui a pouco.
not_enough_names409Não foram encontrados nomes de domínio livres suficientes. Envie alguns domínios você mesmo.
not_paid409O pedido ainda não foi pago, então não há nada para cancelar.
reason_required422Cancelar caixas de e-mail exige um motivo entre as opções listadas.
not_connected409Essa ferramenta ainda não está conectada. Conecte primeiro em Configurações, Ferramentas conectadas.
unsupported_tool409Esta ferramenta conectada não pode receber pessoas diretamente. Envie a ela uma exportação a partir da página Exportações.
tool_key_rejected409A ferramenta conectada não aceitou a chave salva. Conecte de novo em Configurações, Ferramentas conectadas.
price_mismatch409O preço que você mostrou à pessoa não é o preço do orçamento. Mostre o preço do orçamento e pergunte de novo.
quote_other_session409O orçamento foi feito com outra chave ou conexão. Peça um novo orçamento aqui e confirme de novo.
export_failed409A exportação não terminou, então não há nada para enviar. Rode a exportação de novo.
sign_in_failed422O servidor de e-mail não aceitou o login, então a caixa de e-mail não foi conectada. details.test diz o que deu errado no envio e na leitura de respostas.
campaign_not_started409A campanha é um rascunho, então não há nada para pausar. Inicie primeiro.
finder_rate_limit429Mais de 30 buscas individuais no localizador de e-mails neste minuto. Aguarde Retry-After segundos.
finder_daily_limit4292.000 buscas no localizador de e-mails hoje. O limite é zerado à meia-noite UTC.
finder_miss_rate_throttle429A maioria das buscas recentes não encontrou nada, então as buscas ficam reduzidas a 20 por hora por um tempo. Confira os nomes e os domínios.

Algumas operações acrescentam um código próprio, como confirmation_required ou quote_not_found. Cada operação lista os seus códigos na referência. Trate um código que você não conhece pelo seu status HTTP.

O ID da requisição

Toda resposta traz um header X-Request-Id, e todo erro o repete como request_id. Envie o seu próprio ID no header X-Request-Id (de 8 a 64 letras, dígitos, pontos, hífens ou sublinhados) para encontrar uma chamada nos seus próprios logs. Informe o ID quando pedir ajuda.

Requisições por minuto

Cada chave pode enviar esta quantidade de requisições por minuto, e até o segundo número em quaisquer 10 segundos.

PlanoRequisições por minutoEm 10 segundos
Sem plano, chave de API ou CLI3015
Sem plano, assistente de IA6020
Starter6015
Pro24060
Scale600150
Hyperscale1.200300

Sem plano abrange os primeiros 7 dias de uma conta que ainda não escolheu um plano e as contas que usam créditos comprados antes. Um teste grátis de um plano tem os limites desse plano. A chave de uma conta sem plano e sem créditos recebe 402 plan_required em toda chamada, incluindo GET /api/v1/account.

Toda resposta a uma chamada com chave traz X-RateLimit-Limit (requisições por minuto), X-RateLimit-Remaining (requisições restantes neste minuto) e X-RateLimit-Reset (segundos até o minuto recomeçar). Acima de qualquer um dos dois limites você recebe 429 rate_limited com um header Retry-After. Aguarde essa quantidade de segundos e tente de novo.

Revelar pessoas tem mais um limite em todos os planos: uma conta revela até 200 pessoas por minuto. Acima disso você também recebe 429 rate_limited.

Buscas e contagens

Buscas, contagens e prévias são grátis. Elas são limitadas por conta, somando todas as chaves e o conector, então uma segunda chave não acrescenta mais.

PlanoPor minutoContagens por diaLinhas de prévia por dia
Sem plano, chave de API ou CLI10500500
Sem plano, assistente de IA201.0001.000
Starter30sem limitesem limite
Pro60sem limitesem limite
Scale90sem limitesem limite
Hyperscale120sem limitesem limite

Sem plano, buscas e contagens também trazem X-RateLimit-Daily-Limit e X-RateLimit-Daily-Remaining. Uma prévia traz até 10 pessoas por chamada.

Limites diários por chave

Sem plano, cada chave também tem limites diários. Em um plano, só o localizador de e-mails tem um; os créditos limitam o resto. Os limites diários são zerados à meia-noite UTC. GET /api/v1/account mostra o que resta hoje.

O quêPor diaPor chamada
Pessoas reveladas, por filtros100 (sem limite em um plano)25
Linhas de exportação50.000 (sem limite em um plano)50.000 por arquivo, 500.000 por lote
Buscas no localizador de e-mails2.00030 por minuto, listas de até 10.000 linhas

Uma conta sem plano também encontra até 10 e-mails novos por dia no total: revelações, resultados do localizador de e-mails e linhas de exportação contam juntos, e um e-mail que a conta já tinha não conta.

Acima de um limite diário você recebe 429 daily_limit_reached. Para mais pessoas do que o limite diário de revelações, salve uma lista, exporte-a ou adicione-a a uma campanha; esses caminhos foram feitos para milhares de pessoas. O localizador de e-mails responde com códigos próprios: finder_rate_limit (por minuto), finder_daily_limit (por dia) e finder_miss_rate_throttle (a maioria das buscas não encontrou nada).

Páginas

Toda lista recebe limit e cursor. A resposta mantém a sua própria chave (por exemplo campaigns ou people) e acrescenta total, limit, offset, next_cursor e has_more. Passe next_cursor como cursor para receber a próxima página; ele é null na última página. offset também funciona, se você preferir contar as linhas você mesmo.

Algumas listas terminam antes ou paginam do seu próprio jeito. As pessoas de uma campanha são paginadas com after definido como next_after, em uma ordem fixa, e essas páginas não trazem next_cursor. As respostas de uma campanha são paginadas do mesmo jeito, com after e next_after. A lista de campanhas alcança as primeiras 500 campanhas; cursor pagina dentro delas. A caixa de entrada, as respostas de uma campanha e as pessoas de uma campanha também aceitam um filtro de data (updated_after e received_after, ou created_after) em 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 é o mínimo que existe, por exemplo quando uma lista chegou ao seu tamanho máximo.

Novas tentativas seguras

Envie um header Idempotency-Key com qualquer escrita: criar, alterar, excluir, responder, encaminhar e qualquer coisa que gaste créditos ou dinheiro. Use um novo valor aleatório para cada nova ação e o mesmo valor quando tentar de novo.

  • A mesma chave com o mesmo body dentro de 24 horas retorna a primeira resposta, com o header Idempotent-Replayed: true. Nada é feito duas vezes.
  • A mesma chave com outro body responde 409 idempotency_conflict.
  • Enquanto a primeira requisição ainda está em andamento, uma nova tentativa responde 409 idempotency_in_progress. Aguarde um pouco e tente de novo.
  • Erros não são guardados, então você pode corrigir o problema e tentar de novo com a mesma chave.
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}'

Campanhas que não podem ser iniciadas

POST /api/v1/campaigns/{id}/launch responde launch_blocked enquanto algo estiver faltando, por exemplo um e-mail, uma caixa de e-mail com espaço livre hoje ou pessoas. details.blockers lista cada item em palavras simples. GET /api/v1/campaigns/{id} mostra a mesma lista como launch_blockers, para que você corrija tudo antes de tentar.

Nesta página