Error Codes

API error responses and solutions

The Onysoft API returns standard HTTP status codes and detailed error messages.

HTTP Status Codes

Code	Meaning	Description
`200`	OK	Request completed successfully
`202`	Accepted	Asynchronous task created (video/image/music)
`400`	Bad Request	Invalid request format or missing parameter
`401`	Unauthorized	Invalid or missing API key
`402`	Payment Required	Insufficient balance
`403`	Forbidden	Project suspended, model blocked or access denied
`404`	Not Found	Model not found or wrong endpoint
`413`	Payload Too Large	Request size too large (max 10MB — for base64 images)
`422`	Unprocessable Entity	Model not supported (KieAI side)
`429`	Too Many Requests	Rate limit or token limit exceeded
`500`	Internal Server Error	Server error

Error Response Format

                JSON
            

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Yetersiz bakiye. Lütfen bakiye yükleyin."
  }
}
            

Common Errors and Solutions

invalid_api_key

Your API key is invalid or has been deactivated. Create a new key from the Dashboard.

insufficient_balance

Your balance is insufficient for this operation. Add balance from the Dashboard.

model_not_found

The specified model was not found. Make sure the model ID is correct.

rate_limit_exceeded

You have exceeded the per-minute request limit. Wait a moment and try again.

daily_token_limit_exceeded

You have reached the daily token limit defined for this model. Ask your administrator (partner) for a new limit or wait for the daily reset.

monthly_token_limit_exceeded

You have reached the monthly token limit defined for this model. It resets on the first day of the month.

daily_request_limit_exceeded

You have reached the daily request-count limit defined for this model.

model_blocked

This model is blocked for the project/customer. Contact your partner or admin for access.

free_model_rate_limit

You have exceeded the free model usage limit. At most 5 requests can be sent within 24 hours.

payload_too_large

The request size is too large. If you are uploading a base64 image, shrink the image (max 10 MB) or send it directly via a public URL.

generation_failed

Video/image/music generation failed. This is usually a temporary issue on the KieAI side — try another model or try again in a few minutes.

unsupported_model

The model was not found in the DB or has is_active = 0. For the current model list, call GET /v1/models.