---
title: Errors
description: Error response format, error types, and HTTP status codes for the Wireflow API.
updated: 2026-10-03
---

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:

```json
{
  "error": "Workflow not found"
}
```

Some errors include additional fields for context:

```json
{
  "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)

```json
{ "error": "Missing Authorization header" }
```

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

```json
{ "error": "Invalid API key" }
```

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

### Validation Errors (400)

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

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

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

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

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

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

### Permission Errors (403)

```json
{ "error": "Forbidden" }
```

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

### Credit Errors (402)

```json
{
  "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)

```json
{
  "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](/docs/api/rate-limits).

### Not Found Errors (404)

```json
{ "error": "Workflow not found" }
```

```json
{ "error": "Execution not found" }
```

### Server Errors (500)

```json
{ "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.

---

Documentation index: fetch https://www.wireflow.ai/llms.txt for the full list of Wireflow docs.