error-codes.mdx

title	Error Codes
description	Understanding and handling API errors

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.

Error codes

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

**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**:
```json
{
  "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**:
```json
{
  "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](https://modelslab.com/dashboard/api-keys)

**Cause**: Insufficient credits or expired subscription.

**Example Response**:
```json
{
  "status": "error",
  "message": "Insufficient credits. Please add more credits to continue."
}
```

**Solution**: Add credits or renew your subscription from your [dashboard](https://modelslab.com/dashboard) or view [pricing plans](https://modelslab.com/pricing).

**Cause**: The requested feature is not available on your current plan.

**Example Response**:
```json
{
  "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**:
```json
{
  "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](/rate-limits) for plan-specific queue limits.

**Cause**: An internal server error occurred during processing.

**Example Response**:
```json
{
  "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](https://modelslab.com/status)
3. Contact [support](https://modelslab.com/support) if the issue continues

**Cause**: The service is temporarily unavailable, usually due to high load or maintenance.

**Example Response**:
```json
{
  "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

Get community help Contact support team Check service status