Skip to main content

​
Error Response Format

All API errors follow a consistent JSON structure: 
{
  "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

CodeStatusDescription
200OKRequest succeeded
201CreatedResource created successfully

​
Client Error Codes

CodeStatusDescription
400Bad RequestInvalid request parameters or validation error
401UnauthorizedMissing, invalid, or expired authentication token
403ForbiddenValid authentication but insufficient permissions or tier limits
404Not FoundRequested resource does not exist
429Too Many RequestsRate limit exceeded

​
Server Error Codes

CodeStatusDescription
500Internal Server ErrorUnexpected server error
503Service UnavailableService 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
{
  "status": 400,
  "message": "name cannot be empty"
}

{
  "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
{
  "status": 401,
  "message": "Invalid token"
}

{
  "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
{
  "status": 403,
  "message": "Runner limit exceeded for your tier"
}

{
  "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
{
  "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
{
  "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
{
  "status": 500,
  "message": "An unexpected error occurred"
}

​
Validation Errors

Validation errors provide specific feedback about what went wrong: Runner Name Validation: 
{
  "status": 400,
  "message": "name must be between 1 and 100 characters"
}
Endpoint URL Validation: 
{
  "status": 400,
  "message": "endpoint must be a valid HTTP or HTTPS URL"
}
Tags Validation: 
{
  "status": 400,
  "message": "maximum 10 tags allowed"
}
File Size Validation: 
{
  "status": 400,
  "message": "file size exceeds maximum limit of 50MB"
}

​
Workflow-Specific Errors

Workflows can encounter specific error states: Invalid Workflow JSON: 
{
  "status": 400,
  "message": "invalid workflow JSON structure"
}
No Available Runner: 
{
  "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 for correct usage
  5. Contact support at [email protected] with:
    • Request ID (if provided)
    • Timestamp of the error
    • Full error message
    • Steps to reproduce