Skip to main content
Rules that keep spend predictable and retries safe. They apply to people writing integrations and to agents calling the API on their own.

Cap every call with max_credits

Send max_credits on every call that can charge. A call is never charged past it.
  • Read cost on every reply. quoted_credits is the most the call could have charged. charged_credits is what it did charge.
  • Without max_credits, the cap is the full price of what you asked for: max_accounts, limit or the number of records.
  • A call is refused with 402 credits.insufficient only 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 an Idempotency-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.
See Idempotency for how long keys are kept.

Retry by error code

Read code in the error body, not only the status. Honour Retry-After when it is present.
After a 502, 503 or 504 the first call may still be running. A retry with the same key then gets 409 idempotency.in_progress until it finishes. Keep the same key and wait. Sending the request again with a new key, or with no key, can charge twice.
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 review or conflict and is not charged. Fix it before paying for more.
  • Leave spend off 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 with count_only: true first. It delivers nothing and charges nothing.
  • Check total_at_provider and count_is_upper_bound to size the request.
  • Check filters_read_as and rejected to 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 a 200. 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 a level. Decide in code which levels you act on. See Verification.
  • In Enrich, a record with status outreach_ready has a verified work email and a confirmed name.
  • In Validate, treat catch-all and unknown as unproven, not as valid or invalid.

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 an Idempotency-Key so a timeout on your side can be retried safely.

Keep the request ID

Every response carries X-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.