Error Handling

When a request fails, check both the HTTP status code and the code and message in the response body. These are not the same concept: some business exceptions in the current service are returned with HTTP 200, but the code in the response body is not 200, in which case the request has still failed.

Response Structure

An error response is typically:

{
  "code": 1000,
  "message": "Duration must be between 1 and 8 seconds. Please refer to the API documentation for details."
}

Some errors additionally return data:

{
  "code": 1000,
  "message": "Parameter information exception",
  "data": {}
}

The business code for a successful response is 200. When the generic business response object is used, successful responses usually do not return message: "Success".

HTTP Status and Handling Principles

Note: business code 5000 is usually returned with HTTP 200 via the business exception handler, and is not equivalent to HTTP 500; the special path of an internal save failure in batch upload returns HTTP 400 with business code 5000. Clients must judge by the response body code.

For temporary errors — 429, 500, and HTTP 200 with business code 5000 — you can use exponential backoff with random jitter, for example 2 seconds, 4 seconds, 8 seconds, with a maximum retry count. Do not automatically retry parameter, authentication, insufficient-credit, entitlement-unsupported, or resource-not-found errors.

Currently Effective Main Business Error Codes

Framework-Layer and Edge-Layer Errors

Items Defined in the Code That Should Not Be Handled as Currently Effective Errors on Their Own

• 1203 is not defined on the server side. When a batch-upload batch does not exist or has expired, the actual response is HTTP 404 with business code 1200, and message is Batch ID does not exist or has expired..
• Although 1300 is defined in the enum as "unsupported video duration", the current duration-entitlement validation code has been commented out and has no effective throw path. Duration format/range errors usually return HTTP 400 with business code 1000.
• 1500 and 1501 are only defined in the enum; there is currently no effective usage point in the code.
• 1004~1009 are Java enum constant names, not independent business codes; their numeric values are all 1000.

Common Parameter/Request Errors (Business Code 1000)

Bean Validation and ParamException usually return HTTP 400 with code = 1000; however, some query and business services use BizException and return the same business code with HTTP 200, and a few paths for a non-existent model even return code = 1000 with HTTP 404. message carries the actual semantics. The content below preserves the server's actual English copy so clients can match logs; we do not recommend that clients rely on the full copy for business branching.

Basic Fields

Duration Limits

Duration is not a uniform 1~6 seconds. The current code validates by endpoint, model, and input method:

Resolution and Aspect Ratio

Images, Audio, and Reference Inputs

Subject Parameters

Batch File Upload

JSON batch upload supports upload_type = url | base64 。url/base64` images: up to 300 per batch, up to 10 MB each. The specific limits come from the service configuration and may be adjusted per deployment; the numbers in dynamic error messages take precedence.

Image extensions currently supported by the batch-upload controller: jpg, jpeg, png.

Resource Query Errors

Troubleshooting Checklist

1. Check the HTTP status first, then the response body code; HTTP 200 does not necessarily mean success.
2. When code = 1000, go by the specific field indicated in message; do not apply a uniform duration, resolution, or seed range.
3. When code = 1100~1103, check Authorization, Token integrity, the signing key, and the client clock.
4. code = 1302 means insufficient credits; code = 1800 in the current implementation means the queue/concurrent-task capacity is full — the two are handled differently.
5. When querying a task, subject, or batch, confirm the ID comes from the corresponding create endpoint, and that creation and querying use the same account.
6. When encountering 429, HTTP 500, or business code 5000, record the request time, endpoint path, task ID, and full response, then perform a limited number of backoff retries.