> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting: segment auto-suggest failures (AI_SUGGEST_FAILED)

> Fix a 502 AI_SUGGEST_FAILED on POST /api/v1/segments/auto-suggest — split the LLM round-trip failure from the parse and unavailable siblings, retry the transient ones, and fall back to the manual segment builder on the deterministic ones.

# 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:

| Code                  | HTTP | Cause                                                                                                                                                                                                  | Fix                                                                                                                                                                               |
| --------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AI_SUGGEST_FAILED`   | 502  | The AI generation round-trip failed before producing a reply — an LLM-provider timeout against the request's \~30-second deadline, a provider-side error, or a malformed prompt the provider rejected. | Retry once — the same input usually succeeds on a second attempt. If it recurs, check the [status page](https://status.orbit.devotel.io) and then escalate with the `request_id`. |
| `AI_PARSE_FAILED`     | 422  | The model answered, but the reply was not valid JSON and the suggestions could not be extracted.                                                                                                       | Retry once — the model is sampled per call and the second attempt usually parses. If it persists across retries, fall back to the manual segment builder and open a ticket.       |
| `SERVICE_UNAVAILABLE` | 503  | Auto-suggest is not enabled on this deployment.                                                                                                                                                        | Use the manual segment builder — a retry returns the same 503.                                                                                                                    |

A typical 502 envelope:

```json theme={null}
{
  "error": {
    "code": "AI_SUGGEST_FAILED",
    "message": "Could not generate segment suggestions. Try again, or use the manual segment builder.",
    "status": 502
  },
  "meta": {
    "request_id": "req_01HZXK8FJ2",
    "timestamp": "2026-09-24T08:12:44.119Z"
  }
}
```

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](https://status.orbit.devotel.io) 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

* [Segments API reference](/api-reference/segments) — the endpoint contract,
  including the sibling `422 AI_PARSE_FAILED` and `503 SERVICE_UNAVAILABLE`
  envelopes.
* [AI auto-suggest concepts](/concepts/audience-autosuggest-and-cohort-export) —
  how suggestions are generated, preview-counted, and materialized.
* [Error Code Reference](/reference/error-codes) — the full code catalog.
* [Troubleshooting hub](/reference/troubleshooting-hub) — the parent index of
  every runbook.