Errors

HTTP status codes Runflow returns and the error envelope shape.

Envelope

Errors return a JSON body with code, message, and optional errors[]:

{
  "code": "PERMISSION_DENIED",
  "message": "Your account is not authorized to access this resource.",
  "errors": null
}

Field	Type	Notes
code	string	Machine-friendly identifier. Stable across releases.
message	string	Human-friendly message. May change.
errors[]	array	Field-level details for 422 Unprocessable Entity.

Status codes

Code	Meaning	Action
400	Bad request shape.	Check your JSON body against the spec.
401	Missing or invalid token.	Confirm Authorization: Bearer <token> is present and the key is active.
402	Payment required.	Check the balance at GET /v1/billing/balance, then top up from app.runflow.io/settings/billing.
403	Permission denied or email not verified.	Check the code for PERMISSION_DENIED vs EMAIL_NOT_VERIFIED.
404	Resource not found.	Verify the path and the resource ID.
409	Conflict.	Usually a duplicate create or a race. Refetch and retry.
422	Validation error.	Read errors[] for per-field details.
503	Service unavailable.	Backoff and retry with jitter. Check /v1/readiness for component status, contact support if persistent.

Common codes

code	Cause
UNAUTHORIZED	Bad or missing token.
PERMISSION_DENIED	Token lacks scope for this operation.
EMAIL_NOT_VERIFIED	User has not confirmed their email.
INSUFFICIENT_CREDIT	Account balance is too low. Top up.
RUN_NOT_FOUND	The run_id does not exist or belongs to another org.
MODEL_UNAVAILABLE	Provider downtime. Retry or pick a sibling model.

Run failures

When POST /v1/models/.../runs succeeds but the run later fails, the run object carries failure_code, failure_stage, and failure_message:

{
  "id": "01J0...",
  "status": "failed",
  "failure_code": "INPUT_VALIDATION_FAILED",
  "failure_stage": "preprocess",
  "failure_message": "image dimensions exceed 4096x4096"
}

Retry strategy

• 5xx and 429: exponential backoff with jitter, max 5 attempts.
• 4xx other than 429: do not retry, fix the request.
• Network errors: same as 5xx.

Related

Authentication

401 and Bearer header detail.

Pricing

402 and credit balance.