Error Codes

Error response format

All error responses follow this structure:

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

Field	Type	Description
`code`	`number`	The HTTP status code
`error_code`	`string`	Stable machine-readable classification
`message`	`string`	A human-readable description that may change without notice

Branch on error_code, not by parsing message. Every public API response also includes an X-Request-Id header. Record that identifier with your error logs and include it when contacting support. Common stable values include:

`error_code`	Meaning
`invalid_json`	The request body is not valid JSON
`invalid_request_body`	The decoded body is not a JSON object
`missing_required_fields`	`model`, `task_type`, or `input` is missing
`invalid_model`	The requested model is unsupported
`unsupported_task_type`	The model does not support the requested task type
`invalid_task_input`	A model- or task-specific input field is invalid
`invalid_audio_format`	`audio_format` was sent with an unsupported value
`audio_format_unavailable`	MP3 conversion is temporarily switched off — omit `audio_format` and you will receive the provider’s original file
`missing_api_key` / `invalid_api_key`	Authentication failed
`insufficient_credits`	Available credits do not cover the task
`account_suspended`	The authenticated account cannot create tasks
`rate_limited`	The API key exceeded its current quota
`task_not_found`	The task does not exist or belongs to another account
`upstream_provider_error`	An upstream model provider failed
`internal_error`	Sunor encountered an unexpected 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,
  "error_code": "missing_required_fields",
  "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,
  "error_code": "invalid_api_key",
  "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,
  "error_code": "insufficient_credits",
  "message": "Insufficient credits: available 3, required 10"
}

403 — Forbidden

The authenticated account is not currently allowed to create a task.

{
  "code": 403,
  "error_code": "account_suspended",
  "message": "Account suspended"
}

404 — Not Found

The requested resource does not exist. Common causes:

Invalid task ID
Task belongs to a different user

{
  "code": 404,
  "error_code": "task_not_found",
  "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,
  "error_code": "rate_limited",
  "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,
  "error_code": "internal_error",
  "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,
  "error_code": "upstream_provider_error",
  "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()
            request_id = response.headers.get("X-Request-Id", "unknown")
            raise Exception(
                f"API error {error['error_code']} "
                f"(request {request_id}): {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();
      const requestId = response.headers.get("X-Request-Id") || "unknown";
      throw new Error(
        `API error ${error.error_code} (request ${requestId}): ${error.message}`,
      );
    }
  }
}

Getting Started

Billing

Models

Guides

Resources

Error Codes

Error response format

Error codes

400 — Bad Request

401 — Unauthorized

402 — Payment Required

403 — Forbidden

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

​403 — Forbidden

​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

403 — Forbidden

404 — Not Found

429 — Too Many Requests

500 — Internal Server Error

502 — Bad Gateway

Handling errors

Example error handling