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.