TTAPI uses a consistent JSON response structure across endpoints so your application can handle success and failure cases in a predictable way.
Success
{
"status": "SUCCESS",
"message": "success",
"data": {
"jobId": "b8bd3ff0-4349-4b71-8938-5e13aefa64fe"
}
}
Failure
{
"status": "FAILED",
"message": "Parameter error",
"data": null
}
HTTP status codes
| HTTP code | Meaning | Common cause |
|---|
200 | Request succeeded | Submission or fetch succeeded |
400 | Bad request | Invalid or missing parameters |
401 | Unauthorized | Missing or invalid TT-API-KEY |
402 | Insufficient balance | Not enough quota |
404 | Not found | Wrong endpoint or missing resource |
429 | Too many requests | Short-term request rate exceeded |
499 | Queue exhausted | Not enough queue capacity for that product |
500 | Server error | Internal service failure |
504 | Timeout | Long-running synchronous request timed out |
Business statuses
The status field inside the JSON body describes the task state at the business level.
| Status | Meaning |
|---|
PENDING_QUEUE | Waiting in queue |
ON_QUEUE | In progress |
SUCCESS | Completed successfully |
FAILED | Task failed |
Common examples
Successful submission
{
"status": "SUCCESS",
"message": "success",
"data": {
"jobId": "b8bd3ff0-4349-4b71-8938-5e13aefa64fe"
}
}
Successful fetch
{
"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"
]
}
}
Parameter error
{
"status": "FAILED",
"message": "[Invalid parameter] Invalid value for argument: `--v`:`8`",
"data": null
}
Invalid key
{
"status": "FAILED",
"message": "Wrong TT-API-KEY or email is not activated."
}
Notes
- For
4xx responses, check the request first before retrying
- For
5xx responses, retry once or twice, then contact support if the issue persists
- Save the returned
jobId for polling, webhook correlation, and troubleshooting