Error Codes

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

{
  "status": "error",
  "code": "invalid_api_key",
  "message": "Human-readable error description"
}

Generation endpoints return HTTP 200 for failures. /api/v6, /api/v7 and /api/v8 answer errors with a 200 status line and "status": "error" in the body. Branch on the body’s status and code — never on the HTTP status code alone, or a failed generation reads as a success.

Branch on code, not on message: code is a stable token, while message is prose that gets reworded and is sometimes forwarded verbatim from a third-party provider.

Code	Meaning
`validation_error`	The request payload failed validation. See `errors` for per-field detail.
`invalid_api_key`	The API key is missing, malformed, or does not belong to an active account.
`unauthenticated`	Authentication is required for this endpoint.
`forbidden`	Authenticated but not entitled to this endpoint or model.
`no_subscription`	No active subscription. A paid plan is required.
`insufficient_balance`	Plan allowance exhausted and the wallet cannot cover this request.
`not_found`	The endpoint, model or request id does not exist.
`rate_limited`	Rate window or concurrency limit exhausted. See the `RateLimit-*` headers.
`provider_error`	An upstream model provider refused or failed the request. `message` is forwarded from the provider.
`upstream_unavailable`	A ModelsLab service or GPU worker could not be reached. Not billed — retry.
`server_error`	Unexpected server-side failure. Retry, then contact support with the request id.

The same list is published as x-error-model.codes in openapi.json, typed as the GenerationError schema.

Some legacy endpoints may return messege instead of message. Handle both fields for compatibility.

Control-plane errors

The agent control plane (/api/agents/v1) uses real HTTP status codes and a different envelope — every response, success or failure, has the same three keys:

{
  "data": null,
  "error": {
    "code": "insufficient_scope",
    "message": "This token does not have the required scope: wallet:read.",
    "details": { "required_scope": "wallet:read", "granted_scopes": ["models:read"] }
  },
  "meta": { "request_id": "0f8f6b1e-7a4a-4a3f-9a1b-2c9c1d0e5f21" }
}

On success error is null and data carries the payload. Quote meta.request_id when reporting a failure. Typed as AgentErrorEnvelope in agents-openapi.json.

HTTP Status Codes

400 - Bad Request

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.

401 - Unauthorized

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:

Verify your API key is correct
Check the key is included in the request body
Ensure the key hasn’t been revoked in your dashboard

402 - Payment Required

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 from your dashboard or view pricing plans.

403 - Forbidden

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.

429 - Too Many Requests

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:

Wait for current requests to complete
Implement exponential backoff in your code
Consider upgrading your plan for higher limits

See Rate Limits for plan-specific queue limits.

500 - Server Error

Cause: An internal server error occurred during processing.Example Response:

{
  "status": "error",
  "message": "Internal server error. Please try again."
}

Solution:

Wait a few seconds and retry the request
If the error persists, check the status page
Contact support if the issue continues

503 - Service Unavailable

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:

Field	Error Message	Solution
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

Get Started

MCP Web API

Agents API (Control Plane)

Client SDKs

Guides

Error Codes

Error Response Format

Error codes

Control-plane errors

HTTP Status Codes

Common Error Scenarios

Missing Required Parameters

Invalid Model ID

Image URL Issues

Handling Errors in Code

Python

JavaScript

Validation Errors

Processing Status vs Errors

Getting Help

Discord

Email Support

Status Page

​Error Response Format

​Error codes

​Control-plane errors

​HTTP Status Codes

​Common Error Scenarios

​Missing Required Parameters

​Invalid Model ID

​Image URL Issues

​Handling Errors in Code

​Python

​JavaScript

​Validation Errors

​Processing Status vs Errors

​Getting Help

Discord

Email Support

Status Page

Error Response Format

Error codes

Control-plane errors

HTTP Status Codes

Common Error Scenarios

Missing Required Parameters

Invalid Model ID

Image URL Issues

Handling Errors in Code

Python

JavaScript

Validation Errors

Processing Status vs Errors

Getting Help