# Errors

> What a failed request looks like and when to retry.

Every failed request comes back in one shape.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "\u2026",
    "retryable": false
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

* **Branch on `code`.** It is stable. `message` is written for people and may change in any release.
* **Retry only when `retryable` is `true`.** The status alone doesn't say: a `503` can be a brief outage worth retrying or a capability this environment doesn't have.
* **Quote `requestId` when you contact support.** It is also the `X-Request-Id` response header, on every response. Send your own `X-Request-Id` (letters, digits, `_`, `-` and `=`, up to 255 characters) and Augenta uses it instead of making one, so your logs and ours share an id.

A rejected document batch also names the entry it refused with an `index` inside `error`.

## Codes most integrations handle

| Situation                      | Codes                                                | What to do                                                                          |
| ------------------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| The request is wrong           | `invalid_request`, `invalid_cursor`                  | Fix the request; `message` names the field. Don't retry unchanged.                  |
| The key is wrong               | `unauthenticated`, `forbidden`, `connector_inactive` | Check the key and its Workspace assignments.                                        |
| The Workspace changed          | `workspace_archived`, `cursor_stale`, `conflict`     | Stop writing to an archived Workspace; restart a stale list from its first page.    |
| Slow down                      | `rate_limited`, `at_capacity`                        | Wait `Retry-After` seconds, then send the same request.                             |
| Augenta is briefly unavailable | Any code with `retryable: true`                      | Retry with backoff, reusing the same `Idempotency-Key` where the request takes one. |
| Out of credit                  | `insufficient_balance`                               | Add credits, then retry with the same operation key.                                |

## Error codes

| Code                      | Status | Retryable | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`         | 400    | no        | The request is malformed: a missing or invalid header, query parameter or body field. `message` names which.                                                                                                                                                                                                                                                                                                                                                                                                |
| `invalid_cursor`          | 400    | no        | A returned page URL or polling bookmark is invalid, or its bound selection was changed. Restart the initial list request; do not edit continuation URLs.                                                                                                                                                                                                                                                                                                                                                    |
| `invalid_batch`           | 400    | no        | Document processing: send 1 to 50 staged documents.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `invalid_document`        | 400    | no        | Document processing: send each document as the descriptor staging returned.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `invalid_sha256`          | 400    | no        | Document processing: `sha256` must be 64 lowercase hex characters.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `invalid_size`            | 400    | no        | Document processing: `size` must be the file's size in bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `invalid_filename`        | 400    | no        | Document upload: the file needs a name of at most 255 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `invalid_media_type`      | 400    | no        | Document upload: `mediaType`, when sent, must be a media type.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `invalid_document_id`     | 400    | no        | Document upload: `documentId`, when sent, must be a non-empty string of at most 500 characters.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `invalid_captured_at`     | 400    | no        | Document upload: `capturedAt`, when sent, must be an ISO-8601 time with an offset.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `invalid_path`            | 400    | no        | Document upload: `path`, when sent, must be the file's relative path, using forward slashes and ending in its name. `message` lists every rule.                                                                                                                                                                                                                                                                                                                                                             |
| `malformed`               | 400    | no        | Document upload: the body is not readable `multipart/form-data`.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `file_required`           | 400    | no        | Document upload: send exactly one `file` part.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `empty`                   | 400    | no        | Document upload: the file is empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `unauthenticated`         | 401    | no        | Missing, invalid or revoked credential.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `insufficient_balance`    | 402    | no        | Add credits, then explicitly retry with the same operation key.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `billing_retry_exhausted` | 409    | no        | The billing operation used three executions or its 24-hour retry window expired.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `forbidden`               | 403    | no        | The credential is valid but can't do this: a key on a route that needs a person's sign-in, a Workspace you aren't a member of, or a Workspace not assigned to the key (or outside a legacy Connector's anchor).                                                                                                                                                                                                                                                                                             |
| `connector_inactive`      | 403    | no        | The key's Connector is disabled or gone. An organization admin can re-enable it.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `not_found`               | 404    | no        | No such resource, or no such route.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `workspace_not_found`     | 404    | no        | No Workspace with this id in your organization.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `experience_not_found`    | 404    | no        | No experience with this id that your credential can see. Ids come from `POST /v1/experiences`.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `engram_not_found`        | 404    | no        | The engram is no longer in this Workspace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `unsupported_content`     | 406    | no        | `X-Augenta-Content` named a response version that isn't served. Send `content-v3`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `conflict`                | 409    | no        | The resource changed since you read it, or the change conflicts with its state: reload it and send a corrected change. For experiences, the same `sid` and `seq` range was already accepted with different `events`; resending it will not succeed. Send new steps under new `seq` numbers.                                                                                                                                                                                                                 |
| `workspace_archived`      | 409    | no        | The Workspace is archived. Its metadata remains readable; memory reads and writes are closed.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `workspace_not_archived`  | 409    | no        | Deleting a Workspace's data: the Workspace is still active. Archive it first.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `cursor_stale`            | 409    | no        | Workspace memory changed during a read or Consolidate completion. Restart the initial list request, or retry Consolidate with the same immutable source input.                                                                                                                                                                                                                                                                                                                                              |
| `synthesis_in_flight`     | 409    | no        | A synthesis pass is already running for this Workspace.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `idempotency_conflict`    | 409    | no        | This `Idempotency-Key` was already used with a different query. Use a new key.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `embedder_mismatch`       | 409    | no        | A server configuration problem. Contact support.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `payload_too_large`       | 413    | no        | The request body is too large.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `too_large`               | 413    | no        | Document upload: the file is larger than the 25 MB upload limit.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `experiences_too_large`   | 413    | no        | Stateless form: send at most 50 experiences per call.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `unsupported_media_type`  | 415    | no        | The request's `Content-Type` or encoding isn't accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `unsupported_type`        | 415    | no        | Document upload: this file type can't be read. `message` says what to send instead.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `not_multipart`           | 415    | no        | Document upload: send the file as `multipart/form-data` with one `file` part.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `empty_query`             | 422    | no        | The query had nothing to search on, such as only stop words.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `evidence_over_budget`    | 422    | no        | `budget_tokens` is too small to hold even the best-matching claim. Raise it.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `precondition_required`   | 428    | no        | Send the resource's current `_etag`, or an `If-Match` header, with the change.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `rate_limited`            | 429    | yes       | Rate limited. Wait the number of seconds in the `Retry-After` header.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `at_capacity`             | 429    | yes       | The deployment is full: Consolidate admission, a busy processing service, synthesis, too many document uploads at once, or recall's answer mode at its concurrency limit. Or, for the stateless forms, every model provider stayed throttled through the model calls' own retries; that interval is longer (30 s), because a resent request runs every model call again. Not your rate limit. Wait the number of seconds in `Retry-After`, then send the same request (or, for recall, use `mode=context`). |
| `internal_error`          | 500    | no        | An unexpected failure. Contact support with the `requestId`.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `store_misconfigured`     | 500    | no        | A server configuration problem. Contact support.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `stateless_not_available` | 501    | no        | One-shot Consolidate compute is not configured in this deployment.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `cognition_failed`        | 502    | yes       | The memory service failed or answered with something unreadable.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `answer_failed`           | 502    | yes       | The model writing the answer failed, or did not finish within the answer deadline (about 55 s). Retry, or use `mode=context`.                                                                                                                                                                                                                                                                                                                                                                               |
| `recall_unavailable`      | 502    | yes       | The recall service could not be reached.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `recall_forward_rejected` | 502    | no        | An internal configuration problem. Contact support.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `service_unavailable`     | 503    | yes       | A service behind the API is briefly unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `service_unconfigured`    | 503    | no        | This capability isn't set up in this environment.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `workos_unavailable`      | 503    | yes       | Your sign-in couldn't be checked right now. Retry; don't sign in again.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `cognition_unavailable`   | 503    | yes       | The memory service isn't serving right now.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `cognition_unconfigured`  | 503    | no        | The memory service isn't set up in this environment.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `engram_vanished`         | 503    | yes       | The Workspace was consolidating during the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `answerer_unavailable`    | 503    | no        | This deployment can't write answers. Use `mode=context`.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `consent_required`        | 503    | no        | This deployment lacks consent to send data to a required external model. Ask the operator to configure consent; `mode=context` only works when its embedding provider is available and consented.                                                                                                                                                                                                                                                                                                           |
| `store_unavailable`       | 503    | yes       | Document upload: storage is briefly unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `estimator_unavailable`   | 503    | yes       | Document estimate: the estimator is briefly unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `estimator_unconfigured`  | 503    | no        | Document estimate: estimates aren't available in this environment.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `recall_timeout`          | 504    | yes       | No response within 15 s (context) or 60 s (answer).                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `operation_timeout`       | 504    | no        | A JSON (non-streaming) Consolidate ran past its synchronous deadline (90 s by default). Send it again with `stream: true`, which keeps the connection alive for long inputs.                                                                                                                                                                                                                                                                                                                                |

When you retry a recall, reuse the same `Idempotency-Key` so it is not counted twice: an `answer_failed` recall has already recorded its activation, and a retry under the same key reuses it.

For `at_capacity`, `error.retryAfterSeconds` carries the same interval as the HTTP
`Retry-After` header. A Consolidate stream may already have committed HTTP 200 when
a downstream service refuses work. In that case it ends with one `error` event;
read `error.code`, `error.retryable` and `error.retryAfterSeconds` from that event.
The committed HTTP status cannot change. Retry only after the interval, keeping
the original input; provisional output is not a completed result.

## Rate limits

Limits apply per key, per minute. Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds), so you can slow down before you hit the limit. A `429` adds `Retry-After`.

## Reserved codes

These codes are defined but the API does not return them; they are listed so a client that
switches on every code knows they exist.

| Code                   | Status | Retryable | Meaning                                                                                               |
| ---------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------- |
| `idempotency_required` | 400    | no        | Not returned by the API, which answers a missing `Idempotency-Key` with `invalid_request`.            |
| `scope_forbidden`      | 403    | no        | Not returned by the API, which reports it as `recall_forward_rejected`.                               |
| `empty_scope`          | 404    | no        | Not returned by the API. Valid empty recall now returns 200 with `noMatch: true`.                     |
| `snapshot_changed`     | 409    | no        | Not returned by the API. A Workspace memory page that changes mid-read is reported as `cursor_stale`. |
| `invalid_scope`        | 422    | no        | Not returned by the API, which composes the scope from your credential.                               |
| `invalid_query`        | 422    | no        | Not returned by the API, which answers an invalid query with `invalid_request`.                       |
