Every failed request comes back in one shape.
{
"error": {
"code": "invalid_request",
"message": "\u2026",
"retryable": false
},
"requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
- Branch on
code. It is stable.messageis written for people and may change in any release. - Retry only when
retryableistrue. The status alone doesn't say: a503can be a brief outage worth retrying or a capability this environment doesn't have. - Quote
requestIdwhen you contact support. It is also theX-Request-Idresponse header, on every response. Send your ownX-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. |