Responses

TTAPI uses a consistent JSON response structure across endpoints so your application can handle success and failure cases in a predictable way.

Unified response format

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

Getting Started

Developer

FAQ

Product Guides

Resources

Unified response format

Success

Failure

HTTP status codes

Business statuses

Common examples

Successful submission

Successful fetch

Parameter error

Invalid key

Notes

​Unified response format

​Success

​Failure

​HTTP status codes

​Business statuses

​Common examples

​Successful submission

​Successful fetch

​Parameter error

​Invalid key

​Notes

Unified response format

Success

Failure

HTTP status codes

Business statuses

Common examples

Successful submission

Successful fetch

Parameter error

Invalid key

Notes