Skip to main content

​
Troubleshooting: segment auto-suggest failures (AI_SUGGEST_FAILED)

The Suggest segments panel on Audience → Segments calls POST /api/v1/segments/auto-suggest and renders the returned suggestions as cards you can materialize in one click. When that call fails, the panel shows an error tile with a retry button, and the API envelope names one of three codes. AI_SUGGEST_FAILED (502) is the transient one — the AI generation round-trip itself broke. Two siblings sit next to it and need different handling: AI_PARSE_FAILED (422), when the model answered but the reply was not usable, and SERVICE_UNAVAILABLE (503), when auto-suggest is not enabled on the deployment. Read error.code off the envelope first — the fix differs per code: A typical 502 envelope:
This is the same retry-versus-error rule the campaign brief generator uses: AI_GENERATION_FAILED on campaign generation is transient and worth one retry; the parse and unavailable siblings are not. Codes do not rename — the envelope always carries the stable code, so branch on the code and never on the message text.

​
What to do

  1. Retry once. AI_SUGGEST_FAILED and AI_PARSE_FAILED are both transient classes in practice — the provider wobble or the one malformed reply clears on the next attempt. The panel’s Try again button issues a fresh request, so use that rather than re-sending a copy of the request yourself.
  2. Steer with a complete definition. The endpoint accepts an optional focus_hint (up to 500 characters) that steers the suggestions. If you typed a vague fragment in the header (“retention”), widen it to a full steer (“focus on contacts whose last purchase is older than 90 days”) and retry — a fully-typed definition gives the model a stable target and lands a parseable reply more often than a bare keyword.
  3. Confirm the segments schema is still callable. Distinguish “no suggestions returned” from “no data to suggest from”: auto-suggest reads your last 30 days of CDP events and returns an empty suggestion list with a note when the org has no signal yet. If the call succeeds but comes back empty, emit events via POST /api/v1/events/track or the CDP track endpoint to seed suggestions; that is not a failure and this page does not apply. A request that 502s against an org that does have event volume is the failure this page covers.
  4. Open a ticket when it recurs. Include the meta.request_id from the failing envelope, the approximate time, and the focus_hint you sent. Support can pull the provider-side trace off the request id without a back-and-forth.

​
Do not retry in a loop

Do not script a tight retry loop against a 502 or 422 on this endpoint. Each attempt spends LLM tokens against the same failure class, so a loop doubles token spend on a deterministic fail — and auto-suggest is rate-limited per tenant, so the loop tripping the 429 is the expected second failure. Retry manually, once, after the immediate cause has had a moment to clear; if it recurs, take the ticket path with the request_id. Likewise, do not treat a 503 as transient — auto-suggest being disabled on the deployment is a fixed state, and every retry returns the same envelope. The manual segment builder is the working path there.

​
When to escalate

Escalate when:
  • AI_SUGGEST_FAILED keeps returning on separate attempts across several minutes while the status page reports all operational.
  • AI_PARSE_FAILED recurs on three or more distinct attempts — that points at a systematic output problem, not a one-off malformed reply.
  • The call succeeds but the suggestions are unusable every time (every card dropped as invalid), and your org does carry event volume.
Send the meta.request_id from two failing envelopes, the focus_hint if you sent one, and the endpoint you called (/api/v1/segments/auto-suggest).

​
See also