The Wireflow API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Format

All errors return a JSON object with an error field:

{
  "error": "Workflow not found"
}

Some errors include additional fields for context:

{
  "error": "Insufficient credits. Required: 10, Available: 3",
  "insufficientCredits": true,
  "requiredCredits": 10,
  "availableCredits": 3,
  "breakdown": [
    { "nodeId": "node-1", "nodeLabel": "Text to Image", "credits": 10 }
  ]
}

HTTP Status Codes

Code	Meaning	When It Happens
400	Bad Request	Missing required fields, invalid node structure, empty workflow
401	Unauthorized	Missing or invalid API key, expired key
402	Payment Required	Insufficient credits to run the workflow
403	Forbidden	No permission to access the resource
404	Not Found	Workflow or execution does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server-side failure

Common Errors

Authentication Errors (401)

{ "error": "Missing Authorization header" }

{ "error": "Invalid API key format. Expected: Bearer sk-..." }

{ "error": "Invalid API key" }

{ "error": "API key has expired" }

Validation Errors (400)

{ "error": "Missing required fields: name, nodes, edges" }

{ "error": "At least one node must be provided" }

{ "error": "All nodes must have an id" }

{ "error": "Node node-1 is missing model.name" }

{ "error": "Workflow is not active" }

{
  "error": "Cannot save workflow with 0 nodes and 0 edges. This appears to be a frontend bug. Reload the page."
}

Permission Errors (403)

{ "error": "Forbidden" }

{ "error": "Forbidden: Cannot resume execution you do not own" }

Credit Errors (402)

{
  "error": "Insufficient credits. Required: 10, Available: 3",
  "insufficientCredits": true,
  "requiredCredits": 10,
  "availableCredits": 3,
  "breakdown": [
    { "nodeId": "node-1", "nodeLabel": "Text to Image", "credits": 10 }
  ]
}

Rate Limit Errors (429)

{
  "error": "Too many workflow executions. Please try again later.",
  "retryAfter": 1711036800
}

The retryAfter field in the JSON body is a Unix timestamp (seconds since epoch), matching the X-RateLimit-Reset header. The Retry-After HTTP header is a relative number of seconds to wait. See Rate Limits.

Not Found Errors (404)

{ "error": "Workflow not found" }

{ "error": "Execution not found" }

Server Errors (500)

{ "error": "An unexpected error occurred" }

If a call that starts a run returns a 500, check GET /workflows/{id}/executions for that run before you retry. A run can start even when the call errors, and a retry of /execute (or of /run without the same Idempotency-Key) bills a second run. Other calls can be retried after a short delay. If the error persists, contact support with the X-Request-Id header value from the response.