Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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
}
FieldTypeNotes
codestringMachine-friendly identifier. Stable across releases.
messagestringHuman-friendly message. May change.
errors[]arrayField-level details for 422 Unprocessable Entity.

​
Status codes

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

​
Common codes

codeCause
UNAUTHORIZEDBad or missing token.
PERMISSION_DENIEDToken lacks scope for this operation.
EMAIL_NOT_VERIFIEDUser has not confirmed their email.
INSUFFICIENT_CREDITAccount balance is too low. Top up.
RUN_NOT_FOUNDThe run_id does not exist or belongs to another org.
MODEL_UNAVAILABLEProvider 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.

Authentication

401 and Bearer header detail.

Pricing

402 and credit balance.