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

# Errors and Limits

> Practical limits, validation boundaries, and the main failure cases to account for.

## Practical limits

### Image generation

* `count` maximum: `20`
* prompt length maximum: `8192` characters
* negative prompt length maximum: `8192` characters
* `inputs` maximum per request: `20`
* `input` shortcut maximum length: `2048` characters
* custom webhook endpoints per request: `5`
* `destination` name maximum length: `64` characters
* `metadata` maximum size: `2 KB`

### Content rating

* URLs per request maximum: `10`
* custom levels minimum: `2`
* custom levels maximum: `7`
* custom level `value` max length: `24`
* custom level `description` max length: `150`

### Alt text

* URLs per request maximum: `10`
* alt text maximum length: `160` characters

### Uploads

* maximum files per request: `10`
* maximum file size: `10 MB`
* minimum file size: `1 KB`
* maximum request body size: `100 MB`
* accepted formats: JPEG, PNG, WEBP

## Concurrency

Mynth does not enforce API concurrency limits. If you want to create many independent tasks, you can send requests in parallel.

## Error response shape

Every API error returns a JSON body with a machine-readable `code` and a human-readable `message`:

```json theme={"theme":"kanagawa-dragon"}
{
  "code": "VALIDATION_ERROR",
  "message": "Count cannot exceed 20 images per request"
}
```

Codes are stable and `SCREAMING_SNAKE_CASE`. `message` is informational and may change; do not parse it.

## Common failure cases

### Unauthorized

HTTP `401` with `code: "UNAUTHORIZED"`.

You used:

* a missing or invalid API key
* a Public Access Token on an owner-only endpoint
* a task token for the wrong task

```json theme={"theme":"kanagawa-dragon"}
{
  "code": "UNAUTHORIZED",
  "message": "Invalid API key"
}
```

### Validation errors

HTTP `400` with `code: "VALIDATION_ERROR"`.

The request shape does not match what Mynth expects, or the selected model does not support a requested capability such as input images.

```json theme={"theme":"kanagawa-dragon"}
{
  "code": "VALIDATION_ERROR",
  "message": "The selected model does not support input images."
}
```

### Insufficient balance

HTTP `422` with `code: "INSUFFICIENT_BALANCE"`.

Task creation reserves cost before generation begins. Requests fail when the account does not have enough available balance.

```json theme={"theme":"kanagawa-dragon"}
{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Insufficient balance."
}
```

### Spending limit exceeded

HTTP `429` with `code: "SPENDING_LIMIT_EXCEEDED"`.

The reserved cost would push the API key's spending limit past its configured cap for the current period. See [Authentication](/reference/authentication#spending-limits).

```json theme={"theme":"kanagawa-dragon"}
{
  "code": "SPENDING_LIMIT_EXCEEDED",
  "message": "Spending limit exceeded"
}
```

### Upload too large

HTTP `413` with `code: "VALIDATION_ERROR"`.

The upload request body exceeds the maximum size.

```json theme={"theme":"kanagawa-dragon"}
{
  "code": "VALIDATION_ERROR",
  "message": "Upload body is too large"
}
```

### Not found

HTTP `404` with `code: "TASK_NOT_FOUND"`.

The task ID does not exist, or you do not have access to it.

```json theme={"theme":"kanagawa-dragon"}
{
  "code": "TASK_NOT_FOUND"
}
```

### Task failed

The task was accepted but did not complete successfully. This is not an HTTP error. Polling will eventually return `status: "failed"`, and webhook delivery will emit `task.image.generate.failed`.

## SDK-specific errors

The JavaScript SDK can also throw:

* `MynthAPIError` - wraps all API errors with the HTTP `status` and the error `code`
* `TaskAsyncTimeoutError` - `wait()` polled for five minutes without completion
* `TaskAsyncUnauthorizedError` - the Public Access Token was rejected
* `TaskAsyncFetchError` - a network fetch failed during polling
* `TaskAsyncTaskFetchError` - the task detail fetch failed
* `TaskAsyncTaskFailedError` - the task completed with `status: "failed"`

Catch `MynthAPIError` to inspect the underlying API error:

```ts theme={"theme":"kanagawa-dragon"}
import { MynthAPIError } from "@mynthio/sdk";

try {
  const task = await mynth.image.generate({ prompt: "..." });
} catch (error) {
  if (error instanceof MynthAPIError) {
    console.error(error.status); // HTTP status code
    console.error(error.code); // API error code, e.g. "VALIDATION_ERROR"
  }
}
```