Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions api-reference/agent-errors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,11 @@
| `422` | Field-level validation failed | Fix the fields listed in the error array. |
| `429` | Public session creation is rate limited | Back off and retry; per-agent and per-IP windows apply to [public agents](/agents/deploy/public-agents) only. |
| `502` | An upstream dependency (conversation gateway, telephony provider) failed | Retry; for a failed phone-number purchase the row stays visible with status `error` and is safe to release. |
| `503` | A platform dependency is temporarily unavailable | Retry with backoff. |

Check warning on line 45 in api-reference/agent-errors.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

api-reference/agent-errors.mdx#L45

Did you really mean 'backoff'?

## 400 vs 422

`422` is field-level validation: unknown fields (the public surface rejects them), length caps, enum values, invalid IANA timezones, dynamic-variable naming. `400` is semantic: an [override](/agents/deploy/authenticated-sessions#overrides) not enabled for the agent, mutually exclusive pagination parameters (`page` + `cursor`), an undecodable cursor, a page offset past 100,000 rows, or a knowledge upload that isn't UTF-8 plain text.

Check warning on line 49 in api-reference/agent-errors.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

api-reference/agent-errors.mdx#L49

Did you really mean 'undecodable'?

Two quirks worth coding around:

Expand All @@ -55,14 +55,14 @@

## 403: what was refused

| Message | Cause |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `Agent is not public` | Anonymous session/widget request against an agent whose public switch is off. |
| `Origin header is required for public agents` | Anonymous request without an `Origin` header — browsers send it automatically, curl must set it. |
| `Origin not allowed` | The page's origin is not on the agent's [allowed origins](/agents/deploy/public-agents#origin-matching). |
| `Agent is unavailable` | The agent's owner can't serve public sessions right now; visitors deliberately can't tell why. |
| `Agent platform is not enabled for this account` | Creating agent resources requires Agents access on your account — contact support if you expect to have it. |
| `Phone number limit reached for this team (N)` | The team holds its maximum of live numbers; release one first. |
| Message | Cause |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Agent is not public` | Anonymous session/widget request against an agent whose public switch is off. |
| `Origin header is required for public agents` | Anonymous request without an `Origin` header — browsers send it automatically, curl must set it. |
| `Origin not allowed` | The page's origin is not on the agent's [allowed origins](/agents/deploy/public-agents#origin-matching). |
| `Agent is unavailable` | The agent's owner can't serve public sessions right now; visitors deliberately can't tell why. |
| `Agent platform is in private beta. Apply for access at https://fish.audio/app/agents` | Creating agent resources requires beta access on your account — sign in and submit the application form at that link. |
| `Phone number limit reached for this team (N)` | The team holds its maximum of live numbers; release one first. |

## 404: anti-enumeration

Expand All @@ -87,7 +87,7 @@

## 5xx

`502` names the failing upstream in the message: the conversation gateway (`Agent gateway is unreachable`) or the telephony provider (`Twilio refused the request: …`). Retrying is safe — a failed phone-number purchase leaves the row visible with status `error`, refunds the day charge, and can be released; a failed release keeps the number live so releasing again retries. `503` means a platform dependency was briefly unreachable; retry with backoff.

Check warning on line 90 in api-reference/agent-errors.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

api-reference/agent-errors.mdx#L90

Did you really mean 'backoff'?

## Going further

Expand Down
Loading