# Errors

> Every refusal uses a JSON body with code, status, debugMessage and data, except the per-minute limit, which answers with no body.

## 400 Bad Request

| Code | When |
|---|---|
| `content-required` | `content` is missing, blank, or the write is refused as empty content. |
| `id-invalid` | The `id` contains `/` or is longer than 512 characters. |
| `nul-character` | The text contains a U+0000 character. |
| `invalid-ingestion` | The body has an unknown field, the batch is empty, has more than 1,000 items, or repeats an `id`. `debugMessage` names the item. |
| `audience-unknown` | `audience` is set to a value other than omitted or `project`. |
| `invalid-deletion` | The delete body is not valid: `ids` is empty, has more than 1,000 entries, or is not a list. |
| `identity-required` | A recall carries no `identity`. |
| `recall-query-required` | `query` is missing from a recall request. |
| `recall-sort-invalid` | `sort` is not `relevance` or `chronological`. |
| `recall-range-invalid` | `occurredFrom` is after `occurredTo`. |
| `recall-level-invalid` | `level` is not `low`, `medium`, `high` or `extra-high`. |
| `recall-level-conflict` | `level` and `maxTokens` are both sent. |
| `recall-budget-invalid` | `maxTokens` is below 256. |
| `invalid-recall` | `limit` is outside 1 to 200, or the body is not the shape of a recall. |
| `acting-user-required` | An app-key call carries no `X-Harny-User` header. |
| `identity-invalid` | An export names an identity that is empty or longer than 200 characters. |
| `cursor-invalid` | An export cursor is not one this API returned. |

## 401 Unauthorized

| Code | When |
|---|---|
| `unauthorized` | The key is missing, unknown or revoked. |

## 403 Forbidden

| Code | When |
|---|---|
| `identity-mismatch` | A body `identity` does not match the acting user. |

## 404 Not Found

| Code | When |
|---|---|
| `not-found` | The `ingestionId` is not a send of this user, or an exported identity is not a person of this app. |
| `data-point-not-found` | The data point does not exist. With bulk delete, `data.ids` lists the missing ids and nothing is deleted. |

## 409 Conflict

| Code | When |
|---|---|
| `idempotency-conflict` | The same `idempotencyKey` is sent with a different body. |
| `data-point-deleted` | An `id` that has been deleted is sent again. |
| `memory-ids-unknown` | A data point you asked to delete finished its delivery after the call that sent it returned, so its memories are not recorded. Erase the user's data instead. |
| `data-point-processing` | A data point you asked to delete is still being delivered. Nothing is deleted. Try again when the send completes. |

## 413 Payload Too Large

| Code | When |
|---|---|
| `content-too-large` | `content` is over 500,000 characters, or a batch is over 16 MiB, or a webhook body is over 1 MiB. |

## 429 Too Many Requests

| Code | When |
|---|---|
| `project-cap-reached` | A usage quota for your app is used up. |
| `export-rate-limited` | One person was exported 5 times in the last hour. `Retry-After` gives the seconds to wait. |

A per-minute `429` has an empty body and a `Retry-After` header.

## 503 Service Unavailable

| Code | When |
|---|---|
| `pipeline-disabled` | Memory is switched off for the app. |
| `organization-not-ready` | The memory service is not ready. Retry after a short wait. |

## Retrying

Retry on `429` and `503`. Wait the seconds in `Retry-After` when it is present. For a send that stopped partway, send the same `idempotencyKey` and the same body: a finished send returns its original receipt and does not run twice, and a batch resumes at the item that was refused.