Errors and limits

One error shape

Every error answer looks the same. Read error.code to decide what to do and show error.message to people. The message is one plain sentence.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Revealing these people costs 1 credit each and the account has none left. Buy credits or upgrade.",
    "details": { "needed": 25, "balance": 0 }
  },
  "request_id": "req_8f2c1d9e0b7a4c3e9f1a2b3c4d5e6f70",
  "detail": "..."
}

detail holds the older form of the error for clients written before this shape. New code should read error.

Error codes

Some operations add a code of their own, such as confirmation_required or quote_not_found. Each operation lists its codes in the reference. Treat a code you do not know by its HTTP status.

The request id

Every answer carries an X-Request-Id header, and every error repeats it as request_id. Send your own id in the X-Request-Id header (8 to 64 letters, digits, dots, dashes or underscores) to find a call in your own logs. Quote the id when you ask for help.

Requests per minute

Each key may send this many requests a minute, and up to the second number in any 10 seconds.

Every answer to a key call carries X-RateLimit-Limit (requests a minute), X-RateLimit-Remaining (requests left this minute) and X-RateLimit-Reset (seconds until the minute starts again). Above either limit you get 429 rate_limited with a Retry-After header. Wait that many seconds, then try again.

Searches and counts

Searches, counts and previews are free. They are limited per account, across all its keys and the connector, so a second key does not add more.

During the trial, searches and counts also carry X-RateLimit-Daily-Limit and X-RateLimit-Daily-Remaining. A preview holds up to 10 people a call.

Daily limits per key

During the trial and on pay as you go each key also has daily limits. On a plan only the email finder has one; credits bound the rest. Daily limits reset at midnight UTC. GET /api/v1/account shows what is left today.

Above a daily limit you get 429 daily_limit_reached. For more people than the daily reveal limit, save a list, export it or add it to a campaign; those paths are made for thousands of people.

Pages

Every list takes limit and cursor. The answer keeps its own key (for example campaigns or people) and adds total, limit, offset, next_cursor and has_more. Pass next_cursor as cursor to get the next page; it is null on the last page. offset works too, if you prefer counting rows yourself.

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"

When total_is_estimate is true, total is the least there is, for example when a list reached its largest size.

Safe retries

Send an Idempotency-Key header with any write: creating, changing, deleting, answering, forwarding and anything that spends credits or money. Use a new random value for each new action and the same value when you retry it.

• The same key and the same body within 24 hours return the first answer, with the header Idempotent-Replayed: true. Nothing is done twice.
• The same key with a different body answers 409 idempotency_conflict.
• While the first request is still running, a retry answers 409 idempotency_in_progress. Wait a moment and try again.
• Errors are not stored, so you can fix the problem and retry with the same key.

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}'

Campaigns that cannot launch

POST /api/v1/campaigns/{id}/launch answers launch_blocked while something is missing, for example an email, a mailbox with room left today, or people. details.blockers lists each one in plain words. GET /api/v1/campaigns/{id} shows the same list as launch_blockers, so you can fix them before you try.