Error Codes

Error response format

When a request fails, the API returns a JSON response with success: false and an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid JSON body"
  }
}

Field	Type	Description
`success`	boolean	Always `false` for errors
`error.code`	string	Machine-readable error code
`error.message`	string	Human-readable description

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request body, missing required fields, or invalid media URL
`UNAUTHORIZED`	401	Missing or invalid API key
`PAYMENT_REQUIRED`	402	Insufficient credit balance to complete the request
`FORBIDDEN`	403	API key is disabled or has expired
`NOT_FOUND`	404	Resource not found (invalid model, generation ID, etc.)
`RATE_LIMITED`	429	Too many requests — rate limit exceeded
`INTERNAL_ERROR`	500	Unexpected server error

Handling errors

Retryable errors

Some errors are transient and can be retried:

429 RATE_LIMITED — wait for your rate limit window to reset, then retry.
500 INTERNAL_ERROR — retry with exponential backoff.

Exponential backoff

For retryable errors, use exponential backoff to avoid overwhelming the API:

import time
import requests

def request_with_retry(url, headers, json_body, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json_body)

        if response.status_code == 429 or response.status_code >= 500:
            wait = 2 ** attempt  # 1s, 2s, 4s, 8s, 16s
            print(f"Retrying in {wait}s (attempt {attempt + 1})")
            time.sleep(wait)
            continue

        return response

    raise Exception("Max retries exceeded")

async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429 || response.status >= 500) {
      const wait = 2 ** attempt * 1000;
      console.log(`Retrying in ${wait}ms (attempt ${attempt + 1})`);
      await new Promise((r) => setTimeout(r, wait));
      continue;
    }

    return response;
  }

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

Non-retryable errors

These errors require fixing the request before retrying:

400 VALIDATION_ERROR — check your request body for invalid fields or missing required parameters.
401 UNAUTHORIZED — verify your API key is correct and included in the Authorization header.
402 PAYMENT_REQUIRED — add credits to your account at Billing.
403 FORBIDDEN — check that your API key is enabled and has not expired.
404 NOT_FOUND — verify the model slug, task type, or generation ID.