This document details the unified return format for all API interfaces, the meaning of status codes, and error return examples to help developers quickly locate API call issues and parse return data.
All API interfaces return data in JSON format. Whether the request succeeds or fails, the return structure remains consistent for easy frontend unified parsing and handling.
{
"status": "SUCCESS", // Status code (success is fixed as 'SUCCESS')
"message": "success", // Hint message (success defaults to returning success)
"data": { // Core return data (structure differs by interface, see respective API documentation)
// Specific business data returned by the interface
}
}
{
"status": "FAILED", // Failed status code (failure is fixed as 'FAILED')
"message": "Parameter error", // Error hint message (detailed explanation of error reason)
"data": null // No valid data on failure, fixed as null
}
II. HTTP Status Code Classification and Explanation
Status codes follow HTTP standard status code specifications, with extensions for certain custom status codes based on business scenarios. Classified by type below for quick identification of error types by developers.
| Status Code | Explanation | Common Scenarios |
|---|
| 200 | Request succeeded | Generation interface request succeeded, query interface query succeeded |
| 400 | Parameter error | Parameters empty, format does not meet requirements, parameter type error |
| 401 | Unauthorized | TT-API-KEY not carried, TT-API-KEY incorrect or forged |
| 402 | Insufficient balance | Account balance insufficient |
| 404 | Requested resource does not exist | Incorrect interface address, requested resource does not exist |
| 429 | Requests too frequent | Multiple calls to the same interface in a short time, exceeding interface rate limit threshold |
| 499 | Insufficient queues | User product queue insufficient |
| 500 | System error | Server code exception, database exception, third-party service call failure |
| 504 | Request timeout | Response timeout, synchronous and time-consuming interfaces recommend using api.ttapi.org domain |
III. Business Status Code Classification and Explanation
Business status codes refer to the status field in the response JSON data, representing the business request state.
| Status Code | Explanation |
|---|
PENDING_QUEUE | Task is waiting in queue |
ON_QUEUE | Task is being processed |
SUCCESS | Task completed successfully |
FAILED | Task execution failed |
IV. Common Return Examples
The following are return examples for high-frequency scenarios. Developers can reference this format to parse API return data and troubleshoot abnormal issues.
4.1 Success Example (Generation Interface)
{
"status": "SUCCESS",
"message": "success",
"data": {
"jobId": "b8bd3ff0-4349-4b71-8938-5e13aefa64fe"
}
}
4.2 Success Example (Query Interface)
{
"status": "SUCCESS",
"message": "",
"jobId": "8ddd973f-b5ff-4192-b418-b37fb65c65f3",
"data": {
"action": "imagine",
"jobId": "8ddd973f-b5ff-4192-b418-b37fb65c65f3",
"progress": "100",
"prompt": "A cute kitten",
"quota": "2",
"discordImage": "https://cdn.ttapi.io/midjourney/2025-11-14/20260307_024522_19cf9806e1c7438b.png",
"cdnImage": "https://cdn.ttapi.io/midjourney/2025-11-14/20260307_024522_19cf9806e1c7438b.png",
"width": 960,
"height": 1200,
"hookUrl": "https://webhook-test.com/40bb50795afa242aee8c837617cd72e9",
"components": [
"upsample1","upsample2","upsample3","upsample4","reroll","variation1","variation2","variation3","variation4"
],
"seed": null,
"images": [
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84tl.png",
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84tr.png",
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84bl.png",
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84br.png"
]
}
}
4.3 Failure Example (Parameter Error)
{
"status": "FAILED",
"message": "[Invalid parameter] Invalid value for argument: `--v`:`8`",
"data": null
}
4.4 Failure Example (TT-API-KEY Error)
{
"status": "FAILED",
"message": "Wrong TT-API-KEY or email is not activated."
}
V. Notes
-
When status code is 400-499, prioritize checking client request parameters, request method, token validity. No need to contact the server.
-
When status code is 500-599, it’s a server exception. Please retry 1-2 times. If still fails, contact technical support.
-
Generation and query interfaces have differences only in successful response format. Failed response format is completely unified. Frontend can handle failure logic uniformly.
-
The jobId returned by generation interfaces can be used for subsequent task progress queries and final result retrieval. It’s recommended to save it properly.
