Skip to main content

​
Error Codes

When an API request fails, sunor returns a JSON error response with an appropriate HTTP status code.

​
Error response format

All error responses follow this structure: 
{
  "code": 400,
  "message": "Missing required fields: model, task_type, input"
}
FieldTypeDescription
codenumberThe HTTP status code
messagestringA human-readable description of the error

​
Error codes

​
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 indicated by the Retry-After header before retrying. 
{
  "code": 429,
  "message": "Rate limit exceeded. Try again in 30 seconds."
}

​
500 — Internal Server Error

An unexpected error occurred on the server. What to do: Retry the request after a short delay. If the error persists, contact support. 
{
  "code": 500,
  "message": "Internal server error"
}

​
502 — Bad Gateway

The upstream AI provider returned an error or is temporarily unavailable. What to do: Retry the request after a short delay. Credits are automatically refunded for failed tasks. 
{
  "code": 502,
  "message": "Upstream provider error"
}

​
Handling errors

Always check the HTTP status code of the response before parsing the body. For 5xx errors, implement exponential backoff with a maximum of 3 retries.

​
Example error handling

import requests
import time

def create_task(api_key, payload, max_retries=3):
    for attempt in range(max_retries):
        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:
            retry_after = int(response.headers.get("Retry-After", 30))
            time.sleep(retry_after)
        elif response.status_code >= 500:
            time.sleep(2 ** attempt)
        else:
            error = response.json()
            raise Exception(f"API error {error['code']}: {error['message']}")

    raise Exception("Max retries exceeded")