Errors
Flow Relay reports two kinds of failure: transport errors on the request itself (HTTP status codes) and generation errors surfaced on a failed job.
HTTP status codes
| Status | When | What to do |
|---|---|---|
400 | A required field is missing or invalid (e.g. no project_id). | Fix the request body or query. |
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. |
Generation error codes
When a job ends with status: "failed", the job carries a structured error_code alongside a human-readable error:
json
{
"job": {
"id": "job_9f3c",
"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. |
Handling failures
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.