# Errors

Every status the Senso API returns, what causes it, and what to do about it.

Senso signals failure with the HTTP status code, and explains it in a JSON body. Branch on the status first; the body tells you which case you hit.

## The error body

Nearly every error comes back with the same two fields:

```json
{ "status": 404, "message": "Node not found" }
```

`status` repeats the HTTP status. `message` is written for people: log it and show it, but do not match on its text.

A request whose body fails validation lists each problem instead:

```json
{
  "status": 400,
  "errors": [
    { "field": "type", "message": "Must be one of: decision consideration awareness evaluation" }
  ]
}
```

A `402` carries a `code` you can branch on: `insufficient_credits` or `spending_limit_reached`.

Each operation's possible errors and their bodies are in the [API Reference](https://docs.senso.ai/api-reference).

## Every status

| Status | Means | What to do |
|--------|-------|------------|
| `400` | The request was malformed, or a field failed validation | Check the `message` or `errors` |
| `401` | The API key is missing or not valid | Send the key in the `X-API-Key` header. See below |
| `402` | Out of credits, or over the spending limit | Check `code`, and your balance with `GET /org/credits/balance` |
| `403` | The key is valid, but this request is not allowed | See below: it has a few different causes |
| `404` | No such endpoint, or no such resource that you can see | See below |
| `409` | Conflicts with something that already exists or is still running | For example, text identical to a document you already have, deleting a document that is still processing, or starting a website import while one is running. Read the `message` before retrying |
| `422` | The request is valid but cannot be carried out | For example, an upload in which no file could be accepted (the body still lists each file's result), turning on auto-publish with no destination set up, or a website import with no website on file |
| `429` | Too many requests | Back off and retry. See [Limits](https://docs.senso.ai/docs/limits) |
| `500` | Something failed on Senso's side | Retry once. For a request that changes something, check whether it took effect before retrying |
| `502` | A service Senso depends on failed | Most often while publishing or unpublishing. Check the content's status before retrying |
| `503` | A service is temporarily unavailable | Retry with backoff |

## 401: the key is missing or not valid

```json
{ "status": 401, "message": "Organization API key or valid JWT token required" }
```

The same answer covers a missing key, a key that is wrong or expired, and a key sent in the wrong header. Send it as `X-API-Key: <your key>`, not as `Authorization: Bearer`. Keys from `senso login` expire after seven days. [API Keys](https://docs.senso.ai/docs/api-keys) shows how to get one.

## 403: the key is valid, but this is not allowed

The `message` says which case it is:

| `message` | Cause |
|-----------|-------|
| `This action requires user authentication` | The operation needs a person signed in to the Senso app. Creating, changing or revoking API keys, and approving a device sign-in, cannot be done with an API key |
| `Your organization doesn't have access to this product` | Your organization does not have the Senso product this endpoint belongs to |
| `No KB scope configured. An admin must grant access to KB content before searching.` | The key is restricted to knowledge base folders, and has none |
| `You do not have permission to modify this resource` | You can see the file or folder, but your access to it does not include changing it |
| `Industry does not match the organization's industry` | You can import prompts only from your organization's own industry |

A key restricted to some folders keeps working on every other endpoint, which is why a `403` or `404` from the knowledge base can be surprising. `GET /org/api-keys` shows whether each key is `scoped`, and `GET /org/api-keys/{id}/kb-permissions` lists its folders. [Permissions](https://docs.senso.ai/docs/permissions) explains roles and folder access.

## 404: no such endpoint, or nothing you can see

A `404` has two causes, and the body tells them apart:

| What comes back | What it means |
|-----------------|---------------|
| Plain text: `404 page not found` | The path does not exist. Check the spelling and the `/api/v1` prefix |
| JSON, such as `{"status": 404, "message": "Node not found"}` | The path exists, but the id does not match anything you can see |

**A file or folder you do not have at least view access to answers `404`, not `403`.** To you, it does not exist. Check the id, and check that your key belongs to the organization that owns it and can see that folder.

A knowledge base document and generated content have separate endpoints. A knowledge base document's id sent to `/org/content/{id}` is a `400`, and is read through `/org/kb/nodes/{id}` instead.

## Next steps

- [Permissions](https://docs.senso.ai/docs/permissions) — roles, folder access and API key scopes
- [API Keys](https://docs.senso.ai/docs/api-keys) — getting a key and checking it works
- [Limits](https://docs.senso.ai/docs/limits) — rate limits and paging
- [API Reference](https://docs.senso.ai/api-reference) — every operation's errors and bodies