Cap every call with max_credits
Sendmax_credits on every call that can charge. A call is never charged past it.
- Read
coston every reply.quoted_creditsis the most the call could have charged.charged_creditsis what it did charge. - Without
max_credits, the cap is the full price of what you asked for:max_accounts,limitor the number of records. - A call is refused with
402 credits.insufficientonly when no credits are available. With a partial balance it delivers the part the balance covers.
Send an Idempotency-Key on anything that can charge
Send anIdempotency-Key header on every POST. Any unique string of 8 to 200 printable characters with no spaces works. A UUID is a good choice.
- The same key with the same body returns the first answer and is charged once. The reply carries the header
Idempotent-Replayed: true. - Keep the key and the body together. When you retry, resend the exact same body with the same key. A different body with the same key is refused with
422 idempotency.key_reused. - Use a new key for each new request. Do not reuse one key for a loop of different calls.
Retry by error code
Readcode in the error body, not only the status. Honour Retry-After when it is present.
See Errors and Rate limits.
Resolve first
Resolve gives each record one stable Agentic ID.- Key your own records on the ID and remove duplicates before you spend on Enrich.
- An ambiguous record comes back as
revieworconflictand is not charged. Fix it before paying for more. - Leave
spendoff unless you want paid sources asked for people that cannot be resolved otherwise. - The ID is what Feedback and Find (
account.id) accept.
Count before you discover
Call Discover withcount_only: true first. It delivers nothing and charges nothing.
- Check
total_at_providerandcount_is_upper_boundto size the request. - Check
filters_read_asandrejectedto see how your filters were read. - Then ask for a small
max_accounts, look at the results, and ask for more.
Keep exclude_seen on
exclude_seen defaults to true on Find, Discover and Lookalike. Companies and people already delivered to your workspace are skipped, so asking again returns new results. Set it to false only when you want the same records again. They are charged again.
Handle short and stopped replies
A reply with fewer results than you asked for is still a200. Read why before asking again.
An agent should stop and report on
source_budget and source_call_limit instead of looping.
Read level before you use a value
Every enriched field carries alevel. Decide in code which levels you act on. See Verification.
- In Enrich, a record with status
outreach_readyhas a verified work email and a confirmed name. - In Validate, treat
catch-allandunknownas unproven, not asvalidorinvalid.
Send feedback
After you use a value, report what happened with Feedback:bounced, replied, wrong_person or confirmed. It charges nothing. A value you report as bounced or wrong_person is no longer served to your workspace.
Allow for long calls
Discover and Lookalike can take minutes. The SDK waits up to 5 minutes per call by default. Set a similar timeout in your own client, and send anIdempotency-Key so a timeout on your side can be retried safely.
Keep the request ID
Every response carriesX-Request-Id, and every reply and error body carries the same value as request_id. Log it with each call and quote it when you ask for help.
