KEY TAKEAWAYS
- Separate card outcomes from transport failures before deciding anything.
- Retry only 429/5xx/transport errors, with jitter and a hard budget.
- Idempotent request IDs make retries safe.
- Fallback gateways absorb provider blips transparently.
- A 50-card pilot removes most error handling surprises for cents.
- Deduplicate and validate before any paid error handling request.
Card verification failures split into two very different worlds: card outcomes (live, dead, unknown) and transport failures (timeout, 5xx, connection reset). Retrying the wrong world wastes money or loses answers.
The error taxonomy
| Signal | Meaning | Action |
|---|---|---|
| HTTP 200, status:false, error auth | Key/config problem | Fix config; do not retry |
| HTTP 200, status:false, error balance | Insufficient balance | Top up; not billed |
| HTTP 429 | Rate limited | Backoff with jitter, retry |
| HTTP 5xx / timeout | Transient | Retry (bounded) |
| result: dead | Definitive card outcome | Never retry |
| result: unknown/charge | No definitive answer | Retry on fallback gateway |
Retry budget, not retry forever
function withBudget(fn, maxTries = 3) {
let attempt = 0;
return (async function next() {
try { return await fn(); }
catch (e) {
if (attempt++ >= maxTries) throw e;
const backoff = Math.min(8000, 500 * 2 ** attempt);
const jitter = backoff * (0.5 + Math.random());
await new Promise(r => setTimeout(r, jitter));
return next();
}
})();
}Jitter prevents thundering herds when a gateway recovers; a hard budget prevents a bad minute from stalling the whole run.
Idempotency
Send a stable request ID per card. The platform deduplicates identical request IDs, so a retried request cannot be processed (or billed) twice. Keep the ID deterministic: sha256(account_id + card_hash + run_id).
Fallback at the platform level
When the primary gateway times out, the platform can retry the same card on a configured fallback before returning an error — see CC gateway routing. Your client retry budget then covers only what the platform could not classify.
Error handling in verification is a routing problem more than a coding problem. The API distinguishes outcomes that deserve different responses: live and dead are decisions, unknown is a fallback signal, and error is a statement about the request or the provider, not the card.
Good handlers make those branches explicit, retry only the free error class with backoff, park unknowns for a fallback pass, and never loop on classified results. The patterns below apply to any language; the guarantees are the same — errors cost nothing, so careful retries are safe.
A concrete error handling example
result = response.get("result", "error")
if result in ("Live", "Dead"):
route_to_workflow(result) # classified — billable, act on it
elif result == "Unknown":
queue_for_fallback(response["id"]) # one fallback pass, then rest
else:
retry_later(response["id"]) # error — free, fix the cause firstLog request identifiers and outcomes, never full card numbers or the API key itself. Reconcile timeout outcomes before assuming failure — the answer may exist even when the response did not arrive. A machine-readable OpenAPI description is available for Postman, Insomnia and client generation. It is a small rule that changes how error handling behaves at scale.
Working with the error handling integration
Authenticate with the API key in a request header; a key in a URL or in client-side code is a leak waiting to happen. Add a circuit breaker: when the error rate crosses a threshold, pause the run and move the remainder to the fallback route. Automation pays off on scheduled workloads: card-on-file audits and route health checks are the classic candidates. Keep the integration boring: one endpoint, one key, explicit handling for the four result classes. Keep it in mind whenever error handling results are reviewed.
Keeping error handling secure
Encrypted transport and account-scoped access are defaults; nothing about the integration requires changing them. The dashboard shows the key once and lets you rotate it at will; rotation is cheap, leaks are not. Log identifiers and outcomes, not card numbers. Debugging almost never requires a PAN. API keys are server-side secrets: they belong in environment configuration, never in URLs, logs or client bundles. It is a small rule that changes how error handling behaves at scale.
From error handling result to decision
- Errors in error handling return to the queue after the cause is fixed, because they produced no answer at all.
- Dead results in error handling route to recovery: dunning, an update-payment prompt or list cleanup.
- In error handling, live results route forward: billing, approval or completion, depending on the workflow.
- Unknown results in error handling get one fallback pass on a second route, then a defined resting state.
Two metrics describe any run: how many cards classify, and how long the pass takes. Everything else is commentary. A result is only as fresh as its timestamp. High-value decisions should use checks that ran close to the moment of the decision. When a result contradicts other evidence, re-check once after a reasonable interval rather than assuming the checker is wrong. That distinction is what keeps error handling decisions clean.
A working routine for error handling
Size batches to the provider ceiling. Past that line, extra concurrency converts into timeouts rather than throughput. Keep a small balance buffer so an interrupted run never leaves a half-classified list and the temptation to re-check everything. Deduplicate before submitting: the same card in a list twice is billed twice if both copies classify. Decide how each outcome is handled before the run starts; a triage plan written after the results arrive is usually just a spreadsheet. That distinction is what keeps error handling decisions clean.
Using error handling on the right side of the line
Check only cards you own or are authorised to process; verification is not a shortcut around cardholder authorization. The platform does not trade card data, and nothing in the system is designed to bypass a cardholder's consent. Verification is a signal, not a guarantee: a live result does not promise that a later charge will be approved. That distinction is what keeps error handling decisions clean.
Running error handling as a process
Keep the API key server-side and regenerable; a leaked key is a billing incident as much as a security one. Track cost per classified card rather than cost per request; it is the only metric that reflects retries and unknown rates. Keep one primary gateway and one fallback, and switch on evidence — error spikes and classified-rate drops — rather than on price alone. Budget verification against the cost of failure, not against zero; the comparison is what makes spend defensible. In error handling work, that is the difference between a signal and a guess.
What each error handling outcome commits you to
When a result contradicts other evidence, re-check once after a reasonable interval rather than assuming the checker is wrong. Dead results are conclusive for the moment and should never be re-checked in the same run; retries on dead cards spend balance for identical answers. Classified rate is the share of cards that produce a definitive answer; it is the first number to compare when switching gateways. Conflating outcomes is the most expensive habit in this area — an error treated as a dead card discards real inventory, and an unknown treated as live inflates confidence. It is a small rule that changes how error handling behaves at scale.