> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfycontrol.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Understanding API errors and how to handle them

## Error Response Format

All API errors follow a consistent JSON structure:

```json theme={null}
{
  "status": 404,
  "message": "requested entity not found"
}
```

**Fields:**

* `status` - HTTP status code as an integer
* `message` - Human-readable error description

## HTTP Status Codes

The ComfyControl API uses standard HTTP status codes to indicate success or failure:

### Success Codes

| Code | Status  | Description                   |
| ---- | ------- | ----------------------------- |
| 200  | OK      | Request succeeded             |
| 201  | Created | Resource created successfully |

### Client Error Codes

| Code | Status            | Description                                                      |
| ---- | ----------------- | ---------------------------------------------------------------- |
| 400  | Bad Request       | Invalid request parameters or validation error                   |
| 401  | Unauthorized      | Missing, invalid, or expired authentication token                |
| 403  | Forbidden         | Valid authentication but insufficient permissions or tier limits |
| 404  | Not Found         | Requested resource does not exist                                |
| 429  | Too Many Requests | Rate limit exceeded                                              |

### Server Error Codes

| Code | Status                | Description                     |
| ---- | --------------------- | ------------------------------- |
| 500  | Internal Server Error | Unexpected server error         |
| 503  | Service Unavailable   | Service temporarily unavailable |

## Common Error Scenarios

### Bad Request (400)

Occurs when request parameters fail validation.

**Example Scenarios:**

* Invalid UUID format
* Missing required fields
* Invalid field types
* Validation constraints not met

```json theme={null}
{
  "status": 400,
  "message": "name cannot be empty"
}
```

```json theme={null}
{
  "status": 400,
  "message": "invalid endpoint URL format"
}
```

### Unauthorized (401)

Authentication failures due to token issues.

**Example Scenarios:**

* Missing Authorization header
* Invalid token format
* Expired token
* Revoked token

```json theme={null}
{
  "status": 401,
  "message": "Invalid token"
}
```

```json theme={null}
{
  "status": 401,
  "message": "Token has expired"
}
```

### Forbidden (403)

Valid authentication but action not allowed.

**Example Scenarios:**

* Tier limits exceeded
* Insufficient permissions
* Resource belongs to another user
* Managed runner access without Pro/Plus tier

```json theme={null}
{
  "status": 403,
  "message": "Runner limit exceeded for your tier"
}
```

```json theme={null}
{
  "status": 403,
  "message": "Managed runners require Pro or Plus tier"
}
```

### Not Found (404)

Requested resource doesn't exist or doesn't belong to you.

**Example Scenarios:**

* Invalid resource ID
* Resource deleted
* Resource belongs to different user

```json theme={null}
{
  "status": 404,
  "message": "requested entity not found"
}
```

### Rate Limited (429)

Too many requests in a short time period.

**Details:**

* Limit: 40 requests per 10 seconds
* Cooldown: 10 seconds
* Identifier: IP address

```json theme={null}
{
  "status": 429,
  "message": "Rate limit exceeded"
}
```

### Internal Server Error (500)

Unexpected server-side error.

**What to do:**

* Retry the request after a brief delay
* Check API status page
* Contact support if issue persists

```json theme={null}
{
  "status": 500,
  "message": "An unexpected error occurred"
}
```

## Validation Errors

Validation errors provide specific feedback about what went wrong:

**Runner Name Validation:**

```json theme={null}
{
  "status": 400,
  "message": "name must be between 1 and 100 characters"
}
```

**Endpoint URL Validation:**

```json theme={null}
{
  "status": 400,
  "message": "endpoint must be a valid HTTP or HTTPS URL"
}
```

**Tags Validation:**

```json theme={null}
{
  "status": 400,
  "message": "maximum 10 tags allowed"
}
```

**File Size Validation:**

```json theme={null}
{
  "status": 400,
  "message": "file size exceeds maximum limit of 50MB"
}
```

## Workflow-Specific Errors

Workflows can encounter specific error states:

**Invalid Workflow JSON:**

```json theme={null}
{
  "status": 400,
  "message": "invalid workflow JSON structure"
}
```

**No Available Runner:**

```json theme={null}
{
  "status": 400,
  "message": "no runner available with matching tags"
}
```

**Workflow Execution Errors:**

When a workflow fails during execution, check the workflow detail endpoint for:

* `error_node` - The ComfyUI node that failed
* `exception_type` - Type of exception
* `exception_message` - Detailed error message

## Need Help?

If you encounter persistent errors:

1. Check this documentation for common solutions
2. Verify your authentication token is valid
3. Ensure you're within rate limits
4. Review the [API Reference](/api/index) for correct usage
5. Contact support at [support@comfycontrol.app](mailto:support@comfycontrol.app) with:
   * Request ID (if provided)
   * Timestamp of the error
   * Full error message
   * Steps to reproduce