Skip to main content

​
Error Response Format

When an error occurs, the API returns a JSON response with the following structure: 
{
  "status": "error",
  "message": "Human-readable error description"
}
Some legacy endpoints may return messege instead of message. Handle both fields for compatibility.

​
HTTP Status Codes

Cause: The request contains invalid parameters or is malformed.Common Issues:
  • Missing required parameter (e.g., prompt, key)
  • Invalid parameter type (e.g., string instead of number)
  • Parameter value out of allowed range
  • Malformed JSON in request body
Example Response:
{
  "status": "error",
  "message": "prompt is required"
}
Solution: Review your request parameters against the API documentation. Ensure all required fields are included and properly formatted.
Cause: Authentication failed or API key is invalid.Common Issues:
  • Missing key parameter in request body
  • Invalid or revoked API key
  • Expired API key
Example Response:
{
  "status": "error",
  "message": "Invalid API key"
}
Solution:
  1. Verify your API key is correct
  2. Check the key is included in the request body
  3. Ensure the key hasn’t been revoked in your dashboard
Cause: Insufficient credits or expired subscription.Example Response:
{
  "status": "error",
  "message": "Insufficient credits. Please add more credits to continue."
}
Solution: Add credits or renew your subscription in the billing section.
Cause: The requested feature is not available on your current plan.Example Response:
{
  "status": "error",
  "message": "This feature requires a premium subscription"
}
Solution: Upgrade your subscription to access this feature.
Cause: You’ve exceeded your rate limit (queue limit).Example Response:
{
  "status": "error",
  "message": "Rate limit exceeded. Maximum 5 queued requests allowed.",
  "retry_after": 30
}
Solution:
  1. Wait for current requests to complete
  2. Implement exponential backoff in your code
  3. Consider upgrading your plan for higher limits
See Rate Limits for plan-specific queue limits.
Cause: An internal server error occurred during processing.Example Response:
{
  "status": "error",
  "message": "Internal server error. Please try again."
}
Solution:
  1. Wait a few seconds and retry the request
  2. If the error persists, check the status page
  3. Contact support if the issue continues
Cause: The service is temporarily unavailable, usually due to high load or maintenance.Example Response:
{
  "status": "error",
  "message": "Service temporarily unavailable. Please try again later."
}
Solution: Wait and retry with exponential backoff. Check the status page for any ongoing maintenance.

​
Common Error Scenarios

​
Missing Required Parameters

// Request missing prompt
{
  "key": "your_api_key",
  "model_id": "flux"
}

// Response
{
  "status": "error",
  "message": "prompt is required"
}

​
Invalid Model ID

// Request with invalid model
{
  "key": "your_api_key",
  "prompt": "A sunset",
  "model_id": "invalid_model_name"
}

// Response
{
  "status": "error",
  "message": "Model not found: invalid_model_name"
}

​
Image URL Issues

// Request with inaccessible image URL
{
  "key": "your_api_key",
  "init_image": "https://example.com/image.jpg"
}

// Response
{
  "status": "error",
  "message": "Unable to fetch image from provided URL"
}
When using image URLs, ensure the image is publicly accessible and returns proper CORS headers.

​
Handling Errors in Code

​
Python

import requests
import time

def make_api_request(payload, max_retries=3):
    url = "https://modelslab.com/api/v6/images/text2img"

    for attempt in range(max_retries):
        response = requests.post(url, json=payload)
        data = response.json()

        if response.status_code == 200:
            if data.get("status") == "success":
                return data["output"]
            elif data.get("status") == "processing":
                # Handle async processing
                return poll_for_result(data["id"])

        elif response.status_code == 429:
            # Rate limited - wait and retry
            retry_after = data.get("retry_after", 30)
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            continue

        elif response.status_code == 401:
            raise Exception("Invalid API key")

        elif response.status_code >= 500:
            # Server error - retry with backoff
            wait_time = 2 ** attempt
            print(f"Server error. Retrying in {wait_time} seconds...")
            time.sleep(wait_time)
            continue

        else:
            raise Exception(f"API Error: {data.get('message', 'Unknown error')}")

    raise Exception("Max retries exceeded")

​
JavaScript

async function makeApiRequest(payload, maxRetries = 3) {
  const url = "https://modelslab.com/api/v6/images/text2img";

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(payload)
      });

      const data = await response.json();

      if (response.ok) {
        if (data.status === "success") {
          return data.output;
        } else if (data.status === "processing") {
          return await pollForResult(data.id);
        }
      }

      if (response.status === 429) {
        const retryAfter = data.retry_after || 30;
        console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }

      if (response.status === 401) {
        throw new Error("Invalid API key");
      }

      if (response.status >= 500) {
        const waitTime = Math.pow(2, attempt) * 1000;
        console.log(`Server error. Retrying in ${waitTime / 1000} seconds...`);
        await new Promise(r => setTimeout(r, waitTime));
        continue;
      }

      throw new Error(`API Error: ${data.message || "Unknown error"}`);

    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }

  throw new Error("Max retries exceeded");
}

​
Validation Errors

When request validation fails, you’ll receive specific error messages:
FieldError MessageSolution
prompt”prompt is required”Include the prompt parameter
prompt”prompt must be a string”Ensure prompt is a text string
width”width must be between 256 and 1024”Use valid dimensions
height”height must be divisible by 8”Use values like 512, 768, 1024
samples”samples must be between 1 and 4”Request 1-4 images per call
guidance_scale”guidance_scale must be between 1 and 20”Use values in valid range

​
Processing Status vs Errors

Not all non-success responses are errors. Some indicate the request is still processing: 
// This is NOT an error - request is processing
{
  "status": "processing",
  "id": "abc123-def456",
  "eta": 30,
  "message": "Your request is being processed"
}
Use the fetch endpoint to check the status of processing requests.

​
Getting Help

Discord

Get community help

Email Support

Contact support team

Status Page

Check service status