Status codes, limits, and failures

Every request ends in exactly one of three outcomes: answer, no answer, or failure. Failures are never retried and never shown to shoppers. The agent simply answers from its other sources for that turn.

Status codes

Your response	Outcome	Failure reason
`200`–`299` with a valid `answer` body	Answer
`200`–`299` with a valid `no_answer` body	No answer
`200`–`299` with a body that is not JSON	Failure	`invalid_json`
`200`–`299` with JSON that fails validation	Failure	`invalid_response`
`200`–`299` with a numeric `version` other than `1`	Failure	`unsupported_version`
`300`–`399` (any redirect)	Failure	`http_error`
`400`–`499`	Failure	`http_error`
`500`–`599`	Failure	`http_error`

A few things worth knowing:

Redirects are not followed, even within your own domain. Configure the final URL in Studio.
204 No Content is a 2xx with an empty body, so it fails as invalid_json. Return {"version": 1, "status": "no_answer"} instead.
Anagram does not read Retry-After, rate-limit headers, or any header other than the status line. A 429 is just another http_error.
Response bodies on error are discarded. Nothing in them reaches the agent, Studio, or the shopper, so include whatever detail helps your own logs.

Limits

Limit	Value	What happens past it
Timeout	8 seconds, end to end (connect, headers, and body)	`timeout` failure. The connection is aborted.
Response body	32 KiB (32,768 bytes)	`oversized_response` failure. The stream is cancelled when the cap is exceeded; `Content-Length` is not trusted.
Requests per shopper turn	2	Further distinct requests are refused without contacting your endpoint.
Identical questions per turn	1	The same question to the same source is sent once and the result shared.
`question` length	1–2,000 characters	Enforced on Anagram’s side before sending.
`answer` length	1–10,000 characters	`invalid_response` failure.
`citations`	8	`invalid_response` failure.
`products`	8	`invalid_response` failure.
Citation `title`	200 characters	`invalid_response` failure.
Any URL (endpoint or citation)	2,048 characters, `https://` only	Endpoint rejected on save; citation fails `invalid_response`.
Auth header value	4,096 characters, no line breaks	Rejected on save.
Retries	0

The 8-second timeout is the one most endpoints trip over. If your system needs a slow model call or a database scan, answer with what you can compute quickly, or precompute. A no_answer in 300 ms is better for the shopper than a perfect answer at 9 seconds, which is discarded.

Failure reasons

These are the values you will see under Test a question in Studio and in Anagram’s diagnostics.

Reason	Meaning	Usual fix
`unsafe_url`	The endpoint is not public HTTPS, or its hostname could not be resolved during URL validation.	Expose the service on a public HTTPS hostname and check its DNS records.
`network_error`	TLS or connection failure, or a failure while reading the response body.	Check certificates, firewall rules, and that the host accepts traffic from the public internet.
`timeout`	No complete response within 8 seconds.	Return faster; see above.
`cancelled`	The caller cancelled the request before it completed.	Nothing to fix on your side.
`http_error`	You returned a 3xx, 4xx, or 5xx. The status code is recorded.	For a redirect, configure the final URL. Otherwise check your logs. A `401`/`403` usually means the saved secret is wrong or expired.
`invalid_json`	Body was not parseable JSON (including empty bodies).	Always return a JSON object, even for “no answer”.
`unsupported_version`	Body parsed but its numeric `version` was not `1`.	Return `"version": 1`. Missing or non-numeric versions produce `invalid_response`.
`invalid_response`	Body parsed but a field broke the rules on The response.	Compare against the field rules table. Common culprits: bare numeric Shopify IDs, `http://` citation URLs, more than 8 products.
`oversized_response`	Body exceeded 32 KiB.	Trim the answer; drop verbose citations.

What the shopper sees

Nothing about a failure. The agent does not apologize for or mention your service. It answers from the catalog and your other knowledge, and the reply may be less specific than it would otherwise be. If the source is failing often, you will notice in Studio when testing, not from shopper complaints. When your source is disabled, no requests are made at all and the agent behaves as if the source did not exist.

Getting Started

Concepts

Brain

Launch

Actions

Analytics

Guides

Integrations

Help

Status codes

Limits

Failure reasons

What the shopper sees

​Status codes

​Limits

​Failure reasons

​What the shopper sees

Status codes

Limits

Failure reasons

What the shopper sees