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

# Errors

> The single error envelope, how to handle failures, and the complete code catalogue.

Every failure the API returns — from a typo in a filter to an internal fault — uses the same JSON envelope and an appropriate HTTP status code. There is exactly one shape to parse, so your error handling is one code path.

```json theme={null}
{
  "error": {
    "code": "LIST_NOT_FOUND",
    "message": "The requested list was not found.",
    "param": null,
    "doc_url": "https://fuseai.com/api/errors/list_not_found",
    "request_id": "req_8f3a1b2c9d4e"
  }
}
```

## The envelope

| Field        | Type           | Description                                                                                                            |
| ------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `code`       | string         | Stable, machine-readable identifier. This is the contract: codes never change meaning, so branch your logic on `code`. |
| `message`    | string         | Human-readable explanation, suitable for logs. Messages may be reworded at any time — never match on them.             |
| `param`      | string or null | The offending request field when validation fails; `null` otherwise.                                                   |
| `doc_url`    | string or null | Link to the code's section in this catalogue.                                                                          |
| `request_id` | string or null | Unique identifier for the request. Quote it when contacting support — it lets us find the exact request in our logs.   |

## Status codes

The HTTP status tells you the class of failure; the `code` tells you the specific one.

| Status | Meaning                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request was malformed or failed validation. `param` names the offending field where possible.                               |
| `401`  | The API key is missing, malformed, expired, or revoked — see [Authentication](/authentication).                                 |
| `402`  | The workspace does not have enough [credits](/concepts/credits) for the operation.                                              |
| `403`  | The key is valid but not scoped for this endpoint — see [Scopes](/concepts/scopes).                                             |
| `404`  | The endpoint or resource does not exist (or is not visible to your workspace).                                                  |
| `409`  | The request conflicts with current state — for example, a list name that is already taken.                                      |
| `422`  | The request is well-formed but semantically invalid — for example, a list with no contacts reachable on the requested channels. |
| `429`  | Rate limit exceeded — see [Rate limits](/concepts/rate-limits).                                                                 |
| `500`  | An unexpected error on our side. The body may be sparse, but it is still enveloped.                                             |

## Handling failures

**Branch on `code`, never on `message`.** Codes are stable identifiers; messages are prose we may reword to be clearer. An integration that string-matches messages will break on a copy edit.

**A `404` does not always mean "never existed."** The API never confirms that another workspace's resources exist, so a `404` on an id you believe you own can also mean the resource belongs to a different workspace. This is deliberate: it prevents anyone from probing ids to map out other tenants' data.

**Retry `429` and `500`; fix everything else.** On `429`, honor the `Retry-After` header before retrying — see [Rate limits](/concepts/rate-limits) for the windows. On `500`, GET requests are safe to retry with backoff; for writes, confirm whether the operation took effect before re-issuing it. Statuses in the 400–422 range describe a problem with the request itself — retrying the same request will fail the same way, so correct it first (for validation errors, `param` points at the field to fix).

### Example: a 404 in full

Requesting rows from a list id that does not exist in your workspace:

```bash theme={null}
curl https://api.tryfuse.ai/api/v1/business/lists/64f1a2b3c4d5e6f7a8b9c0d1/rows \
  -u "af_YOUR_KEY:"
```

```json theme={null}
{
  "error": {
    "code": "LIST_NOT_FOUND",
    "message": "The requested list was not found.",
    "param": null,
    "doc_url": "https://fuseai.com/api/errors/list_not_found",
    "request_id": "req_8f3a1b2c9d4e"
  }
}
```

## Error code catalogue

Every code the API returns, grouped by area. `doc_url` in a live error response links to the matching section below.

### UNAUTHORIZED

`401` — The API token is missing, malformed, expired or revoked. Check that you are sending the key as the Basic-auth username with an empty password, and that the key has not been revoked in API Cockpit — see [Authentication](/authentication).

### INSUFFICIENT\_SCOPE

`403` — This API token is not scoped for this endpoint. The key itself is valid; it was created without the scope this endpoint requires. Create a key with the right scopes, or use an unscoped key — see [Scopes](/concepts/scopes).

### ENDPOINT\_NOT\_FOUND

`404` — No endpoint matches this path and method. Check for typos in the path and confirm the HTTP method against the [API reference](/api-reference); a `POST` to a `GET`-only path returns this code.

### RATE\_LIMITED

`429` — You have exceeded the rate limit. Wait for the window to reset before retrying, honoring the `Retry-After` header — see [Rate limits](/concepts/rate-limits).

### INVALID\_REQUEST

`400` — The request was malformed or failed validation. `param` identifies the offending field when there is one. Fix the request before retrying; the same payload will keep failing.

### UNEXPECTED\_ERROR

`500` — An unexpected error occurred. Retry GET requests with backoff; for writes, verify state first. If it persists, contact support with the `request_id`.

### INSUFFICIENT\_CREDITS

`402` or `422` — The workspace does not have enough credits for the operation. The request is rejected before any work is billed, so a failed request never consumes credits. Check your balance and see [Credits](/concepts/credits).

### LIST\_NOT\_FOUND

`404` — No list with that id is visible to your workspace. Verify the id against `GET /business/lists`; an id belonging to another workspace also returns this code.

### LIST\_NAME\_TAKEN

`409` — A list with that name already exists in your workspace. Pick a different name, or add to the existing list instead of creating a new one.

### COLUMN\_NAME\_TAKEN

`409` — The list already has a column with that name. Column names are unique per list; rename the new column or update the existing one — see [Custom columns](/guides/custom-columns).

### SEARCH\_FILTERS\_INVALID

`422` — The search filters could not be interpreted. Check filter keys and values against `GET /business/prospects/filter-options`, and see [Build a list from search](/guides/build-a-list-from-search) for working examples.

### SAVED\_SEARCH\_NOT\_FOUND

`404` — No saved search with that id is visible to your workspace. List available saved searches with `GET /business/saved-searches`.

### SAVED\_SEARCH\_INVALID

`422` — The saved search exists but its stored filters cannot be run as-is. Recreate or fix the search in the app, then run it again.

### EXCLUDE\_COMPANY\_LISTS\_INVALID

`422` — One or more ids in `excludeCompanyLists` do not resolve to company lists visible to your workspace. Check the ids and that each references a company list, not a contact list.

### CONTACT\_NOT\_FOUND

`404` — No contact with that id is visible to your workspace. Contacts belonging to another workspace also return this code.

### EXPORT\_NOT\_FOUND

`404` — No export job matching that id was found (it may have expired). Start a new export and poll the fresh job id — see [Export a list](/guides/export-a-list).

### CAMPAIGN\_NOT\_FOUND

`404` — No campaign with that id is visible to your workspace. Campaigns belonging to another workspace also return this code.

### CAMPAIGN\_NOT\_APPROVABLE

`409` — The campaign is not in a state that can be approved — it may already be approved or otherwise past the approval step. Fetch the campaign to check its current state — see [Campaigns](/guides/campaigns).

### CAMPAIGN\_NOT\_READY

`422` — The campaign is still being prepared and cannot be acted on yet. Poll the campaign until it is ready, then retry — see [Campaigns](/guides/campaigns).

### INVALID\_CAMPAIGN\_CHANNELS

`422` — The `channels` value is not a valid channel combination for this campaign. Check the accepted values in the [API reference](/api-reference).

### LIST\_INCOMPATIBLE\_WITH\_CHANNELS

`422` — The list has no contacts reachable on the requested channels — it is empty, or no contact has an email address (or LinkedIn profile) for them. Enrich the list or choose channels its contacts can actually be reached on.

### SEQUENCE\_STEP\_NOT\_FOUND

`404` — No sequence step with that id exists on this campaign. List the campaign's steps with `GET /business/campaigns/{campaignId}/steps` to get valid step ids.

### TEMPLATE\_NOT\_FOUND

`404` — The `templateId` does not resolve to a template visible to your workspace. Check the id, or omit it to let the campaign generate copy without a template.

### WRITING\_STYLE\_NOT\_FOUND

`404` — The `writingStyleId` does not resolve to a writing style visible to your workspace. Check the id against the styles configured in the app.

### KNOWLEDGE\_HUB\_NOT\_FOUND

`404` — The `knowledgeHubId` does not resolve to a knowledge hub visible to your workspace. List available hubs with `GET /business/knowledge-hubs` — see [Knowledge hubs](/guides/knowledge-hubs).