Created

Bad Request — text is blank or missing

Unauthorized

Not Found — workspace not found

Unprocessable Entity — the model could not produce a valid filter from the given description, or the
request is too big to translate in one call.

The second case is worth designing for: how long generation takes is driven by how long the ANSWER is,
so a description implying many separate criteria (a list of individual contacts or email addresses,
for example) exceeds the request budget every time, not intermittently. Retrying it unchanged fails
identically — describe the audience by attributes (tags, dates, purchases) or split it into smaller
requests instead.

Too Many Requests, from either of two independent limits:

• Concurrency — two database-heavy filtered reads are already active for this access token and workspace. Wait retry_after seconds (also sent as the Retry-After header); the same request will succeed once one finishes.
• Funnels AI spend cap — the team has reached its Funnels AI budget, so no new generation is started. The body carries limit_reached: true and retrying will not help until the cap resets. This is the cap working rather than a failure, so present it as a notice.

Service Unavailable — retryable. Two conditions land here:

• Transient dependency — a database connection, the model behind filter generation, or another
  dependency was briefly unavailable.
• Request budget exhausted — the request's own wall clock ran out before the filter could be given a
  fair slice, so no records were read. The time went elsewhere in the same request: a slow generation
  call, or earlier pages of the same projection.

The second case is the OPPOSITE of the 422 that says the filter "took longer than 10s to evaluate". That
422 is a statement timeout and is deterministic — the filter selects more than can be evaluated, and an
unchanged retry fails identically. This 503 makes no such claim about the filter, so retrying is worth
doing; if it recurs, narrow the filter or ask for fewer records per call.