Errors - Flowyte

When a request fails, Flowyte returns an RFC 9457 problem+json body with the application/problem+json content type. The HTTP status is the source of truth; the body adds machine-readable detail.

The problem shape

{
  "type": "about:blank",
  "title": "Validation failure",
  "status": 400,
  "detail": "name is required",
  "instance": "/api/v1/agents",
  "code": "validation_error",
  "errors": [
    { "field": "name", "message": "is required" }
  ]
}

Field	Meaning
`status`	HTTP status code (also on the response).
`title`	Short, human-readable summary of the problem type.
`detail`	Explanation specific to this occurrence.
`code`	Stable machine string for branching (e.g. `no_published_version`).
`errors[]`	Field-level validation errors (`field`, `message`), when relevant.

Branch on status and code, not on detail or title — those wording may change.

Common statuses

Status	When
`400 Bad Request`	Malformed or invalid request body; `errors[]` lists the offending fields.
`401 Unauthorized`	Missing or invalid key/session. Check `Authorization: Bearer flowyte_sk_…`.
`403 Forbidden`	Org mismatch, insufficient scope, disallowed origin — or a reserved endpoint (see below).
`404 Not Found`	The resource doesn’t exist in your org’s scope.
`409 Conflict`	Duplicate name, a publish race, or a stale `If-Match` version.
`422 Unprocessable`	Semantically invalid — e.g. a language your plan’s speech engine doesn’t support.
`429 Too Many Requests`	Rate-limited. Honor `Retry-After` and the `RateLimit-*` headers.

Reserved endpoints return 403

Some endpoints in the contract are reserved (planned ahead of release). Calling one returns 403, not 404 — the route exists but isn’t open to you yet. If a correctly-authenticated, correctly-scoped call returns 403, check whether the endpoint is reserved before assuming a permissions bug. The same 403 also covers genuine scope and cross-org denials.

Named problems

A few problems carry a specific code worth handling:

`code`	Status	Meaning
`no_published_version`	`409`	You requested a published-mode session (e.g. a non-draft talk token) but the agent has never been published. Publish it, or use `draftMode: true`.
`integration_unavailable`	`400`	The provider’s OAuth app isn’t configured for this deployment yet.
`integration_not_connected`	`409`	A config helper needs a connected provider (e.g. resolving a Sheet before Sheets is connected).
`sheet_not_accessible`	`404`	The spreadsheet link is wrong or hasn’t been shared with the connected account.
`file_expired`	`404`	An uploaded `fileId` was garbage-collected before it was attached. Re-upload.
`file_too_large`	`413`	The upload exceeds the 25 MB limit.

Optimistic concurrency (409 on `PATCH /agents/{id}`)

Agent autosave uses an If-Match version. If you send a stale version, the server responds 409 with the current agent state and version in the body. Rebase: refetch, re-apply your pending edits, and retry with the new version. For status codes per endpoint, see the API Reference.

​The problem shape

​Common statuses

​Reserved endpoints return 403

​Named problems

​Optimistic concurrency (409 on PATCH /agents/{id})

The problem shape

Common statuses

Reserved endpoints return 403

Named problems

Optimistic concurrency (409 on `PATCH /agents/{id}`)