> ## 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.

# Errors

> The error format, every error code, and what to do about each one.

Every error is an RFC 9457 problem document with the content type `application/problem+json`. Branch on `code`. Do not parse `detail`.

## Shape

```json theme={null}
{
  "type": "https://docs.agentic-id.icustomer.ai/errors/credits.insufficient",
  "title": "Not enough credits",
  "status": 402,
  "code": "credits.insufficient",
  "detail": "Not enough credits for this request: 0 available. Nothing was charged. Add credits, or ask for less.",
  "available": 0,
  "request_id": "req_6f0e1c1e-3a1b-4c55-9a0e-2f7b9d1c8a11"
}
```

**type** `string`

A URL that ends in the error `code`, or in the status when there is no code.

**title** `string`

A short name for the status: `Bad request`, `Unauthorized`, `Not enough credits`, `Forbidden`, `Not found`, `Conflict`, `Request too large`, `Unprocessable`, `Too many requests`, `Service unavailable`, `Timed out`, `Server error`.

**status** `number`

The HTTP status.

**code** `string`

The stable, machine-readable code. Present on every error listed below. It can be missing on an error with no specific cause, such as an unknown path.

**detail** `string`

What went wrong and what to do, in plain words.

**request\_id** `string`

The ID of this request. Quote it when you report a problem. The same value is in the `X-Request-Id` response header of every response.

Some codes add fields:

| Field | Type | On | Meaning |
| - | - | - | - |
| `issues` | array of `path`, `message` | `request.invalid` | Each field that failed |
| `retryAfterSeconds` | number | `rate_limited`, `idempotency.in_progress`, `service.unavailable` | Seconds to wait. Also sent as the `Retry-After` header. |
| `available` | number | `credits.insufficient` | Credits the workspace can spend now |
| `sent` | `false` | `service.unavailable` | The request never started. Nothing was charged. |
| `ambiguous` | `true` | `service.timeout` | The request may have completed |
| `rejected` | array of `field`, `value` | `find.persona_unreadable`, `discovery.filter_unreadable`, `discovery.persona_unreadable` | Filter values that could not be read |
| `seedsRejected` | array | `lookalike.no_profile` | Seeds that could not be used, with the reason |
| `purpose`, `allowed` | string, string\[] | `purpose.not_allowed` | The purpose you sent and the ones your workspace allows |

A `401` also carries a `WWW-Authenticate` header when sign-in is available.

## Error codes

| Status | Code | Meaning | Retry | What to do |
| - | - | - | - | - |
| 400 | `request.invalid` | The body does not match the schema, an ID in the path is not an Agentic ID, or `limit` is out of range | No | Fix the fields in `issues` and send again. Nothing was charged. |
| 400 | `idempotency.key_invalid` | `Idempotency-Key` is not 8 to 200 printable characters with no spaces | No | Send a valid key. A UUID works. |
| 400 | `find.persona_unreadable` | No job title or seniority could be read | No | Give `roles` or `seniority` |
| 400 | `find.account_unknown` | No domain is known for the account ID | No | Pass `account.domain` |
| 400 | `discovery.filter_unreadable` | The account filters could not be read | No | Fix the values in `rejected` |
| 400 | `discovery.persona_unreadable` | The contact filters could not be read | No | Fix the values in `rejected` |
| 401 | `auth.invalid_key` | No credential, or the API key or token is wrong or revoked | No | Send a valid API key or sign in. See [Authentication](https://docs-agentic-id.icustomer.ai/authentication.md). |
| 401 | `auth.token_expired` | Your sign-in token has expired | After refresh | Refresh the token or sign in again |
| 402 | `credits.insufficient` | The workspace has no credits available for this call | No | Add credits, or ask for less. Nothing was charged. See [Credits](https://docs-agentic-id.icustomer.ai/credits.md). |
| 403 | `purpose.not_allowed` | Your workspace has not allowed this `purpose` | No | Use a purpose in `allowed`. See [Data and privacy](https://docs-agentic-id.icustomer.ai/data-privacy.md). |
| 404 | `id.not_held` | Facts or ledger was asked for an ID your workspace does not hold | No | Resolve the person or company first |
| 404 | `feedback.not_held` | An outcome was reported for an ID your workspace does not hold | No | Resolve or enrich it first |
| 409 | `idempotency.in_progress` | The first request with this `Idempotency-Key` is still running | Yes | Wait for `Retry-After`, then send the same request with the same key. You are not charged twice. |
| 422 | `idempotency.key_reused` | This `Idempotency-Key` was used with a different request | No | Use a new key for a new request |
| 422 | `find.account_unresolvable` | The account domain could not be resolved to a company | No | Check the domain |
| 422 | `lookalike.no_profile` | The seeds share no industry, country or size that could be read | No | Use three or more domains of a similar kind |
| 429 | `rate_limited` | Too many requests for this caller or from this address, or too many refused credentials from this address | Yes | Wait for `Retry-After`. See [Rate limits](https://docs-agentic-id.icustomer.ai/rate-limits.md). |
| 502 | `service.error` | Agentic ID hit a fault handling this request | Once | Try once more. If it repeats, report the `request_id`. |
| 503 | `service.unavailable` | Agentic ID is not taking requests for a moment | Yes | Wait for `Retry-After`. With `sent: false`, nothing was sent or charged. |
| 504 | `service.timeout` | Agentic ID took too long to answer. The request may have completed. | With the same key | Send again with the same `Idempotency-Key`, or check `GET /v1/credits` for a charge first. See [Idempotency](https://docs-agentic-id.icustomer.ai/idempotency.md). |
| 500 | none | Something went wrong on our side | Once | Try once more. If it repeats, report the `request_id`. |

### Client-side codes

The [MCP server](https://docs-agentic-id.icustomer.ai/mcp-server.md) and the [CLI](https://docs-agentic-id.icustomer.ai/cli.md) refuse some calls on your machine before anything is sent. These carry `"sent": false` and are never charged.

| Code | Meaning |
| - | - |
| `cap_required` | The call could cost more than 10 credits and has no `max_credits` |
| `auth.missing_key` | Not signed in and no API key is configured |
| `signed_out` | The stored sign-in has ended |
| `unreachable` | The API address did not answer |
| `timeout` | No answer within the client's timeout |

The MCP server and the CLI print errors as `error`, `status`, `message`, `fix` and `request_id`, where `error` is the `code` above.

## Results that are not errors

A `200` answer can still say that less was done than you asked. These are fields in a successful answer, not error codes. You are charged only for what was delivered, and `cost.charged_credits` says how much.

### stopped\_early

`find` and `discover` set `stopped_early` when the search stopped at one of Agentic ID's own limits on paid sources. The `summary` says the same in a sentence.

| Value | Meaning | What to do |
| - | - | - |
| `source_budget` | Agentic ID's daily budget for paid sources is used up | Try again after midnight UTC |
| `request_source_budget` | This one request reached the limit on paid-source spend per request | Ask again for the rest. A new request starts with a fresh limit. |
| `source_call_limit` | The remaining paid source costs more for one lookup than Agentic ID allows | Asking again will not change it. Contact support. |

Nothing is charged for what was not delivered.

### Other partial results

| Field | On | Meaning |
| - | - | - |
| `fewer_than_asked` | discover | Why fewer companies were delivered than `max_accounts`: a limit above, the `max_credits` cap, sources that did not answer, or candidates dropped by a check |
| `incomplete` | validate | One of the email check and the domain check did not complete. The other half is returned with its true charge. Ask for the missing half in a new request. |
| `excluded` | find, discover, lookalike | Why candidates were left out, with counts |
| `rejected` | find, discover | Filter values that could not be read |
| `outcome: "unresolvable"` | resolve | Not enough to resolve it |
| `outcome: "review"` or `"conflict"` | resolve | A possible match needs review, or the identifiers match more than one ID. Nothing was linked or merged. |
| `verdict: "unknown"` | validate | No answer this time. Not charged, and not a verdict against the address. |
| `verdict: "rejected"` | validate | The address was refused before any check. Not charged. |


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