# Errors & limits

> Response codes, task errors and rate limits.

## Response format

Every response is JSON `{"code", "msg", "data"}`. Errors also have an `error` field. **Check `code` in the body** — the HTTP status can be 200 even on errors.

```json
{
  "code": 402,
  "msg": "Insufficient balance",
  "data": {
    "balance": "0.0100",
    "required": "0.0200",
    "topUpUrl": "https://ai.aimixmedia.site/cabinet/billing"
  },
  "error": "insufficient_balance"
}
```

## Error codes

| code | error | Meaning | What to do |
|---|---|---|---|
| 401 | `unauthorized` | Missing, invalid, disabled or deleted key | Check the key |
| 402 | `insufficient_balance` | Not enough balance | Top up |
| 403 | `account_blocked` | Account blocked | Contact support |
| 404 | `task_not_found` | No such task | Check `taskId` |
| 409 | `idempotency_conflict` | `Idempotency-Key` reused with a different body | Use a new key |
| 422 | `validation_error` | Invalid parameter | See `msg` |
| 422 | `unsupported_model` | Unknown model | [Model list](https://docs.aimixmedia.site/en/models) |
| 429 | `rate_limited` | Too many requests | Wait `Retry-After` seconds |
| 500 | `internal_error` | Our failure | Retry later |
| 505 | `model_disabled` | Model temporarily disabled | Pick another one |

## Task errors

If a task was created but failed, recordInfo shows `state: "fail"` and a `failCode`. The money is refunded automatically.

| failCode | Meaning |
|---|---|
| 501 | The model could not or refused to generate (reason in `failMsg`) |
| 504 | Timed out |
| 503 | Model temporarily unavailable |
| 422 | The model rejected the parameters (e.g. a photo could not be downloaded) |
| 500 | Could not get the result |

## Rate limits

| What | Limit |
|---|---|
| Creating tasks and uploads | 20 requests per 10 s per key |
| Reads (recordInfo, list, balance) | 100 requests per 10 s per key |
| Total per IP | 300 requests per 10 s |

Over the limit you get HTTP 429 with `Retry-After`. Concurrent generations are not limited: extra tasks wait in the queue. Need more? Contact us.