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.
{
"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ódigo | Status | O que significa e o que fazer |
|---|---|---|
invalid_request | 400 | Falta algo na requisição ou um valor está errado. A mensagem diz o que corrigir. |
launch_blocked | 400 | A campanha ainda não pode ser iniciada. details.blockers lista o que falta. |
unauthorized | 401 | Nenhuma chave de API, ou a chave está errada ou foi revogada. |
api_key_required | 401 | Esta rota precisa de uma chave de API ou de um login pelo conector, não de uma sessão do navegador. |
plan_required | 402 | O 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_credits | 402 | Créditos insuficientes para esta chamada. details diz quantos são necessários. Nada foi cobrado. |
scope_missing | 403 | Falta à chave um escopo de que esta chamada precisa. Crie uma chave com esse escopo. |
permission_missing | 403 | O seu papel no workspace não permite esta ação. |
forbidden | 403 | Esta ação não é permitida para esta conta. |
not_found | 404 | Esse item não existe no seu workspace. Itens de outros workspaces respondem da mesma forma. |
route_not_found | 404 | Esse endpoint não existe. Confira o caminho na referência. |
method_not_allowed | 405 | O caminho existe, mas não com este método HTTP. details.allowed lista os métodos. |
conflict | 409 | O item está em um estado que não permite isto, por exemplo excluir uma campanha em andamento. |
idempotency_conflict | 409 | Esta Idempotency-Key já foi usada com outro body. |
idempotency_in_progress | 409 | Uma requisição com esta Idempotency-Key ainda está em andamento. Aguarde e tente de novo. |
gone | 410 | O item expirou, por exemplo um arquivo de exportação mais antigo que o seu prazo de guarda. |
quote_expired | 410 | O orçamento é antigo demais. Peça um novo orçamento e confirme de novo. |
validation_error | 422 | Um campo tem o tipo errado ou está faltando. details.fields lista cada problema. |
access_key_activation_required | 428 | Esta chave de acesso convidada ainda não está ativa. Confirme primeiro o e-mail em details.claim_url. |
rate_limited | 429 | Requisiçõ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_reached | 429 | Um 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_error | 500 | Algo falhou do nosso lado. Tente de novo; informe o ID da requisição se continuar falhando. |
unavailable | 503 | Uma parte do serviço está ocupada ou pausada. Tente de novo em um minuto. |
confirmation_required | 400 | Um pedido precisa de confirmed=true, enviado só depois que a pessoa que paga disse sim. |
invalid_webhook_url | 400 | O endereço do webhook precisa ser um endereço https:// público. |
invalid_webhook_events | 400 | Um nome de evento é desconhecido ou nenhum evento foi informado. details.invalid lista os nomes desconhecidos. |
webhook_limit_reached | 400 | Você 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_subscribed | 400 | Uma chamada de teste informou um evento que o webhook não recebe. details.events lista os que ele recebe. |
company_credits_required | 402 | Um perfil completo da empresa custa créditos e a conta tem poucos. details.teaser traz a parte grátis; nada foi cobrado. |
search_busy | 503 | A busca está ocupada agora. Tente de novo em alguns segundos. |
phones_not_in_plan | 402 | Números de telefone vêm com o plano Pro. Nada foi cobrado. |
card_not_charged | 402 | O cartão salvo não foi cobrado. Nada foi comprado; pague por um link de pagamento. |
owner_only | 403 | Só o proprietário do workspace pode fazer isto, por exemplo pedir ou cancelar caixas de e-mail. |
quote_not_found | 404 | O orçamento não existe ou pertence a outra pessoa. Peça um novo orçamento. |
charge_in_progress | 409 | Este orçamento está sendo cobrado agora. Confira o pedido daqui a pouco. |
not_enough_names | 409 | Não foram encontrados nomes de domínio livres suficientes. Envie alguns domínios você mesmo. |
not_paid | 409 | O pedido ainda não foi pago, então não há nada para cancelar. |
reason_required | 422 | Cancelar caixas de e-mail exige um motivo entre as opções listadas. |
not_connected | 409 | Essa ferramenta ainda não está conectada. Conecte primeiro em Configurações, Ferramentas conectadas. |
unsupported_tool | 409 | Esta ferramenta conectada não pode receber pessoas diretamente. Envie a ela uma exportação a partir da página Exportações. |
tool_key_rejected | 409 | A ferramenta conectada não aceitou a chave salva. Conecte de novo em Configurações, Ferramentas conectadas. |
price_mismatch | 409 | O 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_session | 409 | O orçamento foi feito com outra chave ou conexão. Peça um novo orçamento aqui e confirme de novo. |
export_failed | 409 | A exportação não terminou, então não há nada para enviar. Rode a exportação de novo. |
sign_in_failed | 422 | O 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_started | 409 | A campanha é um rascunho, então não há nada para pausar. Inicie primeiro. |
finder_rate_limit | 429 | Mais de 30 buscas individuais no localizador de e-mails neste minuto. Aguarde Retry-After segundos. |
finder_daily_limit | 429 | 2.000 buscas no localizador de e-mails hoje. O limite é zerado à meia-noite UTC. |
finder_miss_rate_throttle | 429 | A 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.
| Plano | Requisições por minuto | Em 10 segundos |
|---|---|---|
| Sem plano, chave de API ou CLI | 30 | 15 |
| Sem plano, assistente de IA | 60 | 20 |
| Starter | 60 | 15 |
| Pro | 240 | 60 |
| Scale | 600 | 150 |
| Hyperscale | 1.200 | 300 |
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.
| Plano | Por minuto | Contagens por dia | Linhas de prévia por dia |
|---|---|---|---|
| Sem plano, chave de API ou CLI | 10 | 500 | 500 |
| Sem plano, assistente de IA | 20 | 1.000 | 1.000 |
| Starter | 30 | sem limite | sem limite |
| Pro | 60 | sem limite | sem limite |
| Scale | 90 | sem limite | sem limite |
| Hyperscale | 120 | sem limite | sem 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 dia | Por chamada |
|---|---|---|
| Pessoas reveladas, por filtros | 100 (sem limite em um plano) | 25 |
| Linhas de exportação | 50.000 (sem limite em um plano) | 50.000 por arquivo, 500.000 por lote |
| Buscas no localizador de e-mails | 2.000 | 30 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.
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.
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.