402 Insufficient Tokens

402 Insufficient Tokens means the request reached the server with valid auth, but your wallet doesn’t have enough to cover the tool’s cost. No work was done, no charge applied.

Quick fix: top up

Call buy_tokens for an immediate top-up.

$
curl -X POST https://api.gtm-tools.sh/api/v0/buy_tokens \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"amount_usd": 25}'

The minimum is $5 (500 tokens). The default rate is $1 = 100 tokens.

After it succeeds, retry the original call. Your balance is updated immediately.

Long-term fix: auto-reload

Set up set_auto_reload so the saved card is charged automatically when the balance dips below your threshold.

$
curl -X POST https://api.gtm-tools.sh/api/v0/set_auto_reload \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "enabled": true,
>
    "threshold_tokens": 200,
>
    "topup_usd": 50
>
  }'

Once configured, batch jobs won’t pause for top-ups.

Auditing spend

If 402s are catching you off guard, audit recent activity:

$
# Current balance + per-tool costs
$
curl https://api.gtm-tools.sh/api/v0/get_token_balance \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"
$
$
# Purchase history (top-ups + auto-reload charges)
$
curl https://api.gtm-tools.sh/api/v0/list_invoices \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"

Common patterns that drain a wallet faster than expected:

• A retry loop on a 5xx or try_again_later: each attempt is charged in full, since the debit lands before the tool reaches its provider.
• list_linkedin_company_employees_posts (80 tokens) called per company in a sweep.
• list_linkedin_company_employees (30 tokens) called without title_filters (returns everyone but still costs the same).

See Token Efficiency for the full list of patterns to avoid.

Free tools to fall back on

Even with a zero balance, these still work:

You can always recover the wallet from a 0-token state; buy_tokens is itself free.