> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agentic-id.icustomer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Rules for callers and agents: cap spend, retry safely, read every reply.

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.

| Endpoint | `max_credits` | What happens at the cap |
| - | - | - |
| [Validate](https://docs-agentic-id.icustomer.ai/products/validate.md) | Optional | Remaining emails return `unknown` with reason `credit_cap`. |
| [Resolve](https://docs-agentic-id.icustomer.ai/products/resolve.md) | Optional | The ID is withheld and `reason` says so. |
| [Enrich](https://docs-agentic-id.icustomer.ai/products/enrich.md) | Required | A record that does not fit is returned with no fields. |
| [Find](https://docs-agentic-id.icustomer.ai/products/find.md) | Required | The search stops before the next person. |
| [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md) | Optional | The search stops. `fewer_than_asked` says so. |
| [Lookalike](https://docs-agentic-id.icustomer.ai/products/lookalike.md) | Optional | The search stops. The summary says so. |

* 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](https://docs-agentic-id.icustomer.ai/idempotency.md) 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.

| Status | Code | Retry? | How |
| - | - | - | - |
| 400 | `request.invalid` and other 400 codes | No | Fix the request. `issues` or `rejected` says what to fix. |
| 401 | `auth.invalid_key` | No | Send a valid credential. |
| 401 | `auth.token_expired` | Yes | Refresh the token, then send again. |
| 402 | `credits.insufficient` | No | Add credits or ask for less. |
| 403 | `purpose.not_allowed` | No | Use a purpose your workspace allows. |
| 404 | `feedback.not_held`, `id.not_held` | No | Resolve the ID first. |
| 409 | `idempotency.in_progress` | Yes | Wait `Retry-After`, send again with the same key. You are not charged twice. |
| 422 | `idempotency.key_reused` | No | Use a new key. |
| 422 | Other 422 codes | No | The request was understood and cannot be done as sent. |
| 429 | `rate_limited` | Yes | Wait `Retry-After`. |
| 502 | `service.error` | Yes | Same `Idempotency-Key`. Quote `request_id` if it keeps happening. |
| 503 | `service.unavailable` | Yes | Wait `Retry-After`, same `Idempotency-Key`. |
| 504 | `service.timeout` | Yes | Same `Idempotency-Key`. The first call may have completed. |

> [!WARNING]
>
> 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](https://docs-agentic-id.icustomer.ai/errors.md) and [Rate limits](https://docs-agentic-id.icustomer.ai/rate-limits.md).

## Resolve first

[Resolve](https://docs-agentic-id.icustomer.ai/products/resolve.md) gives each record one stable Agentic ID.

* Key your own records on the ID and remove duplicates before you spend on [Enrich](https://docs-agentic-id.icustomer.ai/products/enrich.md).
* 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](https://docs-agentic-id.icustomer.ai/products/feedback.md) and [Find](https://docs-agentic-id.icustomer.ai/products/find.md) (`account.id`) accept.

## Count before you discover

Call [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md) 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.

| Signal | Where | What to do |
| - | - | - |
| `fewer_than_asked` | Discover | Read the sentence. Ask again for more, or narrow the filters. |
| `excluded` | Find, Discover, Lookalike | Counts by reason. Nothing listed here was charged. |
| `rejected` | Find, Discover | Filter values that could not be read. Fix them and ask again. |
| `stopped_early: "source_budget"` | Find, Discover | Agentic ID's daily budget for paid sources is used up. Try again after midnight UTC. |
| `stopped_early: "request_source_budget"` | Find, Discover | This request reached its paid-source limit. Ask again for the rest. |
| `stopped_early: "source_call_limit"` | Find, Discover | Asking again will not change it. Contact support. |
| `verdict: "unknown"` | Validate | No answer, not a bad address. Reason `credit_cap` means raise `max_credits` and resend. |
| `incomplete` | Validate | One of the two checks did not finish. Ask for that part again in a new request. |

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](https://docs-agentic-id.icustomer.ai/concepts/verification.md).

* In [Enrich](https://docs-agentic-id.icustomer.ai/products/enrich.md), a record with status `outreach_ready` has a verified work email and a confirmed name.
* In [Validate](https://docs-agentic-id.icustomer.ai/products/validate.md), treat `catch-all` and `unknown` as unproven, not as `valid` or `invalid`.

## Send feedback

After you use a value, report what happened with [Feedback](https://docs-agentic-id.icustomer.ai/products/feedback.md): `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.