Check credits before an enrichment batch run

A 402 does not fail one record. It stops the run. Start a 10,000 record batch with 8,000 credits on the key and it dies somewhere around record 8,000, leaving the rest unenriched and your job half done with no clean way to tell where. The fix is two habits: read the balance before you start, and size the run to it.

A 404 spends, so your balance falls faster than your success count

One credit per answered lookup, and a 404 is an answered lookup. Searching for an identifier that turns out to have no record costs the same retrieval as finding one, so it bills a credit. A cache hit bills a credit too: same data, delivered faster. At $0.005 per credit, a run of 10,000 calls is $50 whether 9,400 return data or all 10,000 do.

So the number that drains your balance is the count of calls you make, not the count that succeed. Budget on the former. The full per-status breakdown is in what an enrichment run costs, and the pricing page has the per-credit rate.

Read the balance before the run

GET /v1/credits is free and spends nothing. Read it against the same ApiKey header as everything else:

curl -s https://api.triguna.ai/v1/credits -H "ApiKey: $TRIGUNA_KEY"

The exact response shape is in the billing reference. The only arithmetic you need is that a run of N identifiers costs N credits, misses included, so if the balance is below N, top up before you start rather than discovering it at record N.

A 402 is terminal and free, so catch it, do not retry it

When the balance hits zero the next call returns 402, and it is loud about why:

HTTP/1.1 402 Payment Required
content-type: text/plain; charset=utf-8

insufficient credits

A 402 is free, so it does not cost you anything, but it is terminal: the balance is still zero on the second attempt, so a retry loop just burns wall-clock and never turns it into a 200. 402 belongs with 400, 401, and 404 in the “do not retry” set, not with 429, 502, and 503. Which status to retry and which to treat as final is the whole subject of which enrichment errors to retry.

Make the run resumable so a 402 is a pause, not a restart

The reason a mid-run 402 hurts is that a naive loop has no memory of what it already paid for. Restart it and you buy the first 8,000 records a second time. Record each completed identifier as you go, keyed on the stable entity_urn rather than the slug you looked it up by, and the next run skips everything already done:

const BASE = 'https://api.triguna.ai/v1';
const headers = { ApiKey: process.env.TRIGUNA_KEY };

// Walk a list of identifiers. Stop cleanly the moment the balance runs out,
// and keep a record of how far you got so the next run resumes, not restarts.
async function enrichAll(urns, done) {
  for (const urn of urns) {
    if (done.has(urn)) continue; // already paid for, never re-fetch

    const res = await fetch(
      `${BASE}/people/profile?entity_urn=${encodeURIComponent(urn)}`,
      { headers },
    );

    if (res.status === 402) {
      console.error('insufficient credits, stopping at', urn);
      break; // terminal: do not retry, it will not become a 200
    }

    // A 404 is answered and billed, so it counts as done, not as pending work.
    if (res.ok || res.status === 404) done.add(urn);

    const charged = res.headers.get('X-Credits-Charged'); // "1" on any answered lookup
    // persist `done` and reconcile `charged` against your balance as your schema requires
  }
  return done;
}

Persist done to a table or a file between runs. A pause on 402 then becomes: top up, run the same command again, pay only for the records you had not reached.

The two-line version

Before a batch: GET /v1/credits, and if the balance is under your call count, top up. During the batch: treat 402 as a clean stop and keep a done set so the resume is free. That is the difference between a run that finishes and a run that strands half your list.

What an enrichment run costs, to estimate the credit count before you check the balance.
Which enrichment errors to retry, for why 402 is terminal and which statuses are worth a backoff.
Nightly backfill, the guide for pacing a large run under the rate limit once the balance is sized.
Start on the five free credits from signup; the enrich on signup guide shows the first call.
The endpoints you are spending on: the Person API and the Company API.

billingbatchreliability

Check your credit balance before a batch run, because a 402 halfway through stalls everything