Flow Relay reports two kinds of failure: transport errors on the request itself (HTTP status codes) and generation errors surfaced on a failed job.
| Status | When | What to do |
|---|---|---|
400 | A field is missing or invalid: no project_id, an unknown source, an out-of-range number, or a filter value outside the source vocabulary. | Read the issues array (see below) – it names the field and lists the allowed values – then fix the request. |
401 | Missing or invalid API key. | Check the Authorization header. |
403 | The action is not allowed (e.g. cross-tenant Discord post). | Verify the resource belongs to your tenant. |
404 | The project, job, or resource is not accessible by this key. | Confirm the id and your access. |
429 | Rate limit exceeded (60/min/key). | Back off and retry. |
500 | An upstream call failed (e.g. discovery). | Retry; if it persists, contact support. |
Validation errors (400)
Generation requests are validated in full before any job is enqueued, so a malformed request never spends credits. The API accepts only the documented fields and vocabularies and rejects everything else. A 400 carries a human error string plus a machine-readable issues array – each entry names the field, explains the problem, and (where the value is drawn from a closed set) lists what is allowed:
{
"error": "Invalid request: sources – \"gihub\" is not a recognized source (+1 more, see \"issues\")",
"issues": [
{
"field": "sources",
"message": "\"gihub\" is not a recognized source.",
"allowed": ["github", "slack", "discord", "linear", "notion", "jira", "gitlab", "bitbucket", "azure_devops", "figma", "confluence", "microsoft_outlook", "microsoft_teams", "sentry", "datadog", "pagerduty", "asana", "gmail", "buildkite", "circleci", "vercel"]
},
{
"field": "maxEvents",
"message": "Out of range (5000). Must be between 1 and 1000."
}
]
}See Filters for the full source vocabulary and the fields each source accepts.
When a job ends with status: "failed", the job carries a structured error_code alongside a human-readable error:
{
"job": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"status": "failed",
"error": "Your plan does not include this flow.",
"error_code": "plan_violation",
"error_meta": { "flow": "architecture_insight" }
},
"result": null
}error_code | HTTP analogue | Meaning | What to do |
|---|---|---|---|
plan_violation | 402 | The flow or model is not included in the current plan. | Upgrade the plan, or pick an included flow. |
quota_exceeded | 429 | Out of included credits and overage is disabled. | Top up credits or enable overage. |
generation_failed | – | The model call or processing failed. | Retry; the message has the specifics. |
no_result | – | The model returned nothing usable. | Retry, optionally with a narrower scope. |
Treat plan_violation and quota_exceeded as user-actionable – surface an upgrade or top-up prompt rather than retrying. For generation_failed and no_result, a single retry is reasonable; persistent failures usually mean the scope has too little (or too much) signal, so adjust filters or the lookback window.