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
`dependency_unavailable`	A dependency Sunor needs was temporarily unreachable; retry after `retry_after_seconds` — your key is unaffected
`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

Failed tasks

The codes above describe a request that failed. A request can also succeed — POST /api/v1/task returns 202, credits are held, the task is created — and the task fail later. Poll GET /api/v1/task/{task_id} and that failure arrives on the task itself:

One case is not a clean either/or: if the provider refuses the submit, we settle the task to failure, refund its credits, and also return 502 upstream_provider_error. So you can hold a 502 while a real, already-refunded failed task exists. That response body carries no task_id — if you need the task, list your recent tasks rather than re-creating one, or the retry pays twice for one intent.

{
  "code": 200,
  "data": {
    "task_id": "0f0c8b2e-...",
    "status": "failure",
    "error": "Your style description is too long - please shorten it to 1000 characters or fewer to continue.",
    "error_code": "invalid_task_input",
    "retryable": false,
    "retry_after_seconds": null
  }
}

The same rule applies: branch on error_code and retryable, not on error. error is prose and may be reworded at any time.

Field	Type	Description
`error_code`	`string \| null`	One of the values below. `null` unless `status` is `failure` or `timeout`
`retryable`	`boolean \| null`	`false` means resending the same request is very unlikely to succeed — change the input, or surface it to a person. Across 180 days of the moderation rejections we classify `false`, one identical resubmission in 634 succeeded. `true` means a later attempt may succeed; whether it succeeds as-is depends on the code — `content_moderation` carries the one verdict that reverses on identical input, while `rate_limited` needs a wait first, which `retry_after_seconds` states only when the provider gives us one
`retry_after_seconds`	`integer \| null`	A wait we can state at this level: the repeat-submission window, and the 300 seconds our own “Service temporarily unavailable” failure asks for. `null` otherwise, which does not always mean there is no wait: some providers put one inside `output` instead, so check there before falling back to your own backoff

`error_code`	When	`retryable`
`content_moderation`	Lyrics, prompt, tags or uploaded audio were rejected on content grounds — copyrighted material, a named artist, a producer tag	usually `false`; `true` for the one verdict the provider is known to reverse on identical audio (uploaded audio judged to contain copyrighted lyrics — 3 of 9 identical resubmissions succeeded, the last one 17 minutes in — and those 9 are every resubmission we have on record, from one caller in one burst, so treat it as “worth retrying” rather than as a rate). Read the field
`invalid_task_input`	An input field was rejected: a prompt or style description the model refuses as too long, uploaded audio too short or unreadable, Suno-only fields sent to Udio	`false`
`rate_limited`	The provider is refusing the request for now: either a repeat submission of the same input too soon (`retry_after_seconds` carries the wait), or its own quota is spent for the period (`retry_after_seconds` is `null` — the reset is the provider’s own boundary and we will not guess it)	`true`
`upstream_provider_error`	The provider timed out, was unavailable, or failed for a reason we cannot attribute to your request	usually `true` — but `false` when the provider itself states the request will not succeed on retry. Always read the field; do not infer it from the code

An over-length prompt currently reports itself twice, and the two disagree. Measured 2026-09-13: the model refuses a prompt over 5,000 characters (“please shorten it to 5000 characters or fewer”). We do not enforce that limit before submitting, so the refusal comes back from the provider — and on POST /api/v1/task it is currently classified as upstream_provider_error (which this table calls “usually true”), while polling the same task returns invalid_task_input / retryable: false.The task-level verdict is the correct one: the rejection is a length check, so the same text fails it again. Keep prompts under 5,000 characters and tags under 1,000. The create-path classification is a known defect on our side, being fixed; until it ships, do not let a 502 on create send you into a retry loop.

An error we have not classified reports upstream_provider_error with retryable: true. We never report invalid_task_input for an unrecognised failure — that would send you to debug a request that was fine.

Retrying correctly

retryable: false means the input must change. Retrying it unchanged consumes a credit hold and a provider round trip each time, and all but never clears — across 180 days, of 634 unchanged resubmissions after a moderation rejection we classify false, exactly one cleared:

const task = await pollTask(taskId);
// `timeout` is a terminal failure too, and it carries the same three fields.
// Branching on "failure" alone silently drops it — measured over 180 days,
// timeouts were 14.6% of all terminal states (1,335 of 9,144).
if (task.status === "failure" || task.status === "timeout") {
  if (!task.retryable) {
    // Nothing to wait for — the request itself has to change.
    throw new TaskInputError(task.error_code, task.error);
  }
  // Bound your retries. `retryable: true` means an attempt *may* succeed, not
  // that it will: a spent provider quota reports it with no wait attached, and
  // an unclassified failure reports it because we would rather you retried than
  // gave up on a task that was fine.
  if (attempt >= MAX_ATTEMPTS) throw new TaskFailedError(task.error_code, task.error);
  await sleep(backoff(attempt, task.retry_after_seconds));
  return retry(attempt + 1);
}

Credits are refunded on every failure, whatever the code.

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"
}

503 — Service Unavailable

A dependency this endpoint needs (our database) was temporarily unreachable, so the request was not processed and nothing was charged. This is not a problem with your API key — the same key keeps working once the dependency recovers. How to fix: Retry after the number of seconds in retry_after_seconds (or the Retry-After header). Read-only requests can be retried directly. For POST /api/v1/task a 503 means the task was never created, so resubmitting is safe.

{
  "code": 503,
  "error_code": "dependency_unavailable",
  "message": "Service temporarily unavailable, please retry",
  "retry_after_seconds": 30
}

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 and 503 responses — a 503 means a dependency of ours was down, not that your key is invalid. 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

Failed tasks

Retrying correctly

Error codes

400 — Bad Request

401 — Unauthorized

402 — Payment Required

403 — Forbidden

404 — Not Found

429 — Too Many Requests

500 — Internal Server Error

503 — Service Unavailable

502 — Bad Gateway

Handling errors

Example error handling

​Error response format

​Failed tasks

​Retrying correctly

​Error codes

​400 — Bad Request

​401 — Unauthorized

​402 — Payment Required

​403 — Forbidden

​404 — Not Found

​429 — Too Many Requests

​500 — Internal Server Error

​503 — Service Unavailable

​502 — Bad Gateway

​Handling errors

​Example error handling

Error response format

Failed tasks

Retrying correctly

Error codes

400 — Bad Request

401 — Unauthorized

402 — Payment Required

403 — Forbidden

404 — Not Found

429 — Too Many Requests

500 — Internal Server Error

503 — Service Unavailable

502 — Bad Gateway

Handling errors

Example error handling