Error Codes

Error response format

All error responses follow this structure:

{
  "code": 400,
  "message": "Missing required fields: model, task_type, input"
}

Field	Type	Description
`code`	`number`	The HTTP status code
`message`	`string`	A human-readable description of the error

400 — Bad Request

The request body is malformed or missing required fields. Common causes:

Missing model, task_type, or input in the request body
Unknown or unsupported task_type
Invalid input parameters for the selected task type

{
  "code": 400,
  "message": "Missing required fields: model, task_type, input"
}

401 — Unauthorized

The API key is missing, invalid, or has been revoked. Common causes:

No x-api-key header in the request
API key does not exist or has been deleted
API key has been disabled

{
  "code": 401,
  "message": "Invalid API key"
}

402 — Payment Required

Your account does not have enough available credits to cover the task cost. How to fix: Top up credits in your dashboard.

{
  "code": 402,
  "message": "Insufficient credits: available 3, required 10"
}

404 — Not Found

The requested resource does not exist. Common causes:

Invalid task ID
Task belongs to a different user

{
  "code": 404,
  "message": "Task not found"
}

429 — Too Many Requests

You have exceeded the rate limit. How to fix: Wait for the duration in retry_after_seconds (or the Retry-After header) before retrying.

{
  "code": 429,
  "message": "Rate limit exceeded.",
  "retry_after_seconds": 60
}

500 — Internal Server Error

An unexpected error occurred on the server. What to do: For read-only requests, retry after a short delay. For POST /api/v1/task, do not automatically submit the same task again when the result is unknown; the current endpoint does not yet accept an Idempotency-Key. If you already received a task_id, poll that task instead.

{
  "code": 500,
  "message": "Internal server error"
}

502 — Bad Gateway

The upstream AI provider returned an error or is temporarily unavailable. What to do: If the provider failure is explicit, the failed task follows the normal refund path. For an uncertain network or gateway result from POST /api/v1/task, do not blindly create another task. If you already received a task_id, poll that task instead.

{
  "code": 502,
  "message": "Upstream provider error"
}

Handling errors

Always check the HTTP status code before parsing the body. Follow Retry-After for 429 responses. Exponential backoff is appropriate for safe/read-only requests. For POST /api/v1/task, an uncertain 5xx or network result should be treated as “create outcome unknown” rather than automatically submitted again. The API does not currently provide Idempotency-Key replay semantics.

Example error handling

import requests
import time

def create_task(api_key, payload, max_rate_limit_retries=3):
    rate_limit_attempts = 0
    while True:
        response = requests.post(
            "https://sunor.cc/api/v1/task",
            headers={
                "Content-Type": "application/json",
                "x-api-key": api_key,
            },
            json=payload,
        )

        if response.status_code == 202:
            return response.json()["data"]
        elif response.status_code == 429 and rate_limit_attempts < max_rate_limit_retries:
            retry_after = int(response.headers.get("Retry-After", 30))
            time.sleep(retry_after)
            rate_limit_attempts += 1
        elif response.status_code >= 500:
            raise RuntimeError(
                "Task creation outcome is unknown; do not submit the same "
                "payload again without an idempotency key."
            )
        else:
            error = response.json()
            raise Exception(f"API error {error['code']}: {error['message']}")

async function createTask(apiKey, payload, maxRateLimitRetries = 3) {
  let rateLimitAttempts = 0;
  while (true) {
    const response = await fetch("https://sunor.cc/api/v1/task", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": apiKey,
      },
      body: JSON.stringify(payload),
    });

    if (response.status === 202) {
      const json = await response.json();
      return json.data;
    } else if (
      response.status === 429 &&
      rateLimitAttempts < maxRateLimitRetries
    ) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "30");
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      rateLimitAttempts += 1;
    } else if (response.status >= 500) {
      throw new Error(
        "Task creation outcome is unknown; do not submit the same payload " +
          "again without an idempotency key.",
      );
    } else {
      const error = await response.json();
      throw new Error(`API error ${error.code}: ${error.message}`);
    }
  }
}

Getting Started

Billing

Models

Guides

Resources

Error Codes

Error response format

Error codes

400 — Bad Request

401 — Unauthorized

402 — Payment Required

404 — Not Found

429 — Too Many Requests

500 — Internal Server Error

502 — Bad Gateway

Handling errors

Example error handling

​Error response format

​Error codes

​400 — Bad Request

​401 — Unauthorized

​402 — Payment Required

​404 — Not Found

​429 — Too Many Requests

​500 — Internal Server Error

​502 — Bad Gateway

​Handling errors

​Example error handling

Error response format

Error codes

400 — Bad Request

401 — Unauthorized

402 — Payment Required

404 — Not Found

429 — Too Many Requests

500 — Internal Server Error

502 — Bad Gateway

Handling errors

Example error handling