> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ttapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

> Unified response format, HTTP status codes, and common error cases

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

```json theme={null}
{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "jobId": "b8bd3ff0-4349-4b71-8938-5e13aefa64fe"
  }
}
```

### Failure

```json theme={null}
{
  "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

<Callout type="info">
  The `status` field inside the JSON body describes the task state at the business level.
</Callout>

| Status          | Meaning                |
| :-------------- | :--------------------- |
| `PENDING_QUEUE` | Waiting in queue       |
| `ON_QUEUE`      | In progress            |
| `SUCCESS`       | Completed successfully |
| `FAILED`        | Task failed            |

## Common examples

### Successful submission

```json theme={null}
{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "jobId": "b8bd3ff0-4349-4b71-8938-5e13aefa64fe"
  }
}
```

### Successful fetch

```json theme={null}
{
  "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

```json theme={null}
{
  "status": "FAILED",
  "message": "[Invalid parameter] Invalid value for argument: `--v`:`8`",
  "data": null
}
```

### Invalid key

```json theme={null}
{
  "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