Skip to content
AugentaDocsOpen console ↗
Errors

Documentation

Get started
View Markdown

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

SituationCodesWhat to do
The request is wronginvalid_request, invalid_cursorFix the request; message names the field. Don't retry unchanged.
The key is wrongunauthenticated, forbidden, connector_inactiveCheck the key and its Workspace assignments.
The Workspace changedworkspace_archived, cursor_stale, conflictStop writing to an archived Workspace; restart a stale list from its first page.
Slow downrate_limited, at_capacityWait Retry-After seconds, then send the same request.
Augenta is briefly unavailableAny code with retryable: trueRetry with backoff, reusing the same Idempotency-Key where the request takes one.
Out of creditinsufficient_balanceAdd credits, then retry with the same operation key.

Error codes

CodeStatusRetryableMeaning
invalid_request400noThe request is malformed: a missing or invalid header, query parameter or body field. message names which.
invalid_cursor400noA 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_batch400noDocument processing: send 1 to 50 staged documents.
invalid_document400noDocument processing: send each document as the descriptor staging returned.
invalid_sha256400noDocument processing: sha256 must be 64 lowercase hex characters.
invalid_size400noDocument processing: size must be the file's size in bytes.
invalid_filename400noDocument upload: the file needs a name of at most 255 characters.
invalid_media_type400noDocument upload: mediaType, when sent, must be a media type.
invalid_document_id400noDocument upload: documentId, when sent, must be a non-empty string of at most 500 characters.
invalid_captured_at400noDocument upload: capturedAt, when sent, must be an ISO-8601 time with an offset.
invalid_path400noDocument upload: path, when sent, must be the file's relative path, using forward slashes and ending in its name. message lists every rule.
malformed400noDocument upload: the body is not readable multipart/form-data.
file_required400noDocument upload: send exactly one file part.
empty400noDocument upload: the file is empty.
unauthenticated401noMissing, invalid or revoked credential.
insufficient_balance402noAdd credits, then explicitly retry with the same operation key.
billing_retry_exhausted409noThe billing operation used three executions or its 24-hour retry window expired.
forbidden403noThe 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_inactive403noThe key's Connector is disabled or gone. An organization admin can re-enable it.
not_found404noNo such resource, or no such route.
workspace_not_found404noNo Workspace with this id in your organization.
experience_not_found404noNo experience with this id that your credential can see. Ids come from POST /v1/experiences.
engram_not_found404noThe engram is no longer in this Workspace.
unsupported_content406noX-Augenta-Content named a response version that isn't served. Send content-v3.
conflict409noThe 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_archived409noThe Workspace is archived. Its metadata remains readable; memory reads and writes are closed.
workspace_not_archived409noDeleting a Workspace's data: the Workspace is still active. Archive it first.
cursor_stale409noWorkspace memory changed during a read or Consolidate completion. Restart the initial list request, or retry Consolidate with the same immutable source input.
synthesis_in_flight409noA synthesis pass is already running for this Workspace.
idempotency_conflict409noThis Idempotency-Key was already used with a different query. Use a new key.
embedder_mismatch409noA server configuration problem. Contact support.
payload_too_large413noThe request body is too large.
too_large413noDocument upload: the file is larger than the 25 MB upload limit.
experiences_too_large413noStateless form: send at most 50 experiences per call.
unsupported_media_type415noThe request's Content-Type or encoding isn't accepted.
unsupported_type415noDocument upload: this file type can't be read. message says what to send instead.
not_multipart415noDocument upload: send the file as multipart/form-data with one file part.
empty_query422noThe query had nothing to search on, such as only stop words.
evidence_over_budget422nobudget_tokens is too small to hold even the best-matching claim. Raise it.
precondition_required428noSend the resource's current _etag, or an If-Match header, with the change.
rate_limited429yesRate limited. Wait the number of seconds in the Retry-After header.
at_capacity429yesThe 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_error500noAn unexpected failure. Contact support with the requestId.
store_misconfigured500noA server configuration problem. Contact support.
stateless_not_available501noOne-shot Consolidate compute is not configured in this deployment.
cognition_failed502yesThe memory service failed or answered with something unreadable.
answer_failed502yesThe model writing the answer failed, or did not finish within the answer deadline (about 55 s). Retry, or use mode=context.
recall_unavailable502yesThe recall service could not be reached.
recall_forward_rejected502noAn internal configuration problem. Contact support.
service_unavailable503yesA service behind the API is briefly unavailable.
service_unconfigured503noThis capability isn't set up in this environment.
workos_unavailable503yesYour sign-in couldn't be checked right now. Retry; don't sign in again.
cognition_unavailable503yesThe memory service isn't serving right now.
cognition_unconfigured503noThe memory service isn't set up in this environment.
engram_vanished503yesThe Workspace was consolidating during the request.
answerer_unavailable503noThis deployment can't write answers. Use mode=context.
consent_required503noThis 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_unavailable503yesDocument upload: storage is briefly unavailable.
estimator_unavailable503yesDocument estimate: the estimator is briefly unavailable.
estimator_unconfigured503noDocument estimate: estimates aren't available in this environment.
recall_timeout504yesNo response within 15 s (context) or 60 s (answer).
operation_timeout504noA 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.

CodeStatusRetryableMeaning
idempotency_required400noNot returned by the API, which answers a missing Idempotency-Key with invalid_request.
scope_forbidden403noNot returned by the API, which reports it as recall_forward_rejected.
empty_scope404noNot returned by the API. Valid empty recall now returns 200 with noMatch: true.
snapshot_changed409noNot returned by the API. A Workspace memory page that changes mid-read is reported as cursor_stale.
invalid_scope422noNot returned by the API, which composes the scope from your credential.
invalid_query422noNot returned by the API, which answers an invalid query with invalid_request.