Errors and Limits - Mynth - Documentation

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:

{
  "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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "code": "TASK_NOT_FOUND"
}

Task failed

The task was accepted but did not complete successfully. This is not an HTTP error. Polling eventually returns status: "failed" with an errors array, and webhook delivery emits the matching *.failed event with the same errors array (for example task.image.generate.failed). See Task error codes.

Task error codes

Failed tasks expose an errors array of { code, message? } objects. The same array appears on:

GET /tasks/:id when status is failed
every *.failed webhook payload

code is stable SCREAMING_SNAKE_CASE and safe to branch on. message is optional, human-readable, and must not be parsed. The array is always present and non-empty on failed tasks. Per-image failures inside a completed generate result use the same { code, message? } shape on result.images[].error — same codes, scoped to that image.

Code	Meaning	What to do
`INVALID_INPUT`	One or more image inputs could not be processed	Ensure input URLs are valid and publicly accessible, then resubmit
`INVALID_PROMPT`	The prompt is empty or outside the allowed length	Fix the prompt; do not retry the same request
`RESTRICTED_CONTENT`	The request was blocked by content moderation	Change the prompt or inputs; do not retry the same request
`CAPABILITY_NOT_SUPPORTED`	The request uses options the selected model does not support	Adjust options or choose a different model
`RATE_LIMITED`	Upstream rate limit hit	Wait briefly, then retry
`TIMEOUT`	The provider did not respond in time	Retry the request
`PROVIDER_ERROR`	The provider failed to process the request	Retry the request
`ENQUEUE_FAILED`	The task could not be queued for processing	Retry the request
`FETCH_FAILED`	The source image URL could not be fetched (rate / alt tasks)	Confirm the URL is reachable and returns an image, then resubmit
`RATING_FAILED`	Content rating could not be completed	Retry; if it persists, try a different image URL
`ALT_GENERATION_FAILED`	Alt text generation could not be completed	Retry; if it persists, try a different image URL
`UNKNOWN_ERROR`	An unclassified failure	Retry once; contact support if it repeats

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:

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"
  }
}

​Practical limits

​Image generation

​Content rating

​Alt text

​Uploads

​Concurrency

​Error response shape

​Common failure cases

​Unauthorized

​Validation errors

​Insufficient balance

​Spending limit exceeded

​Upload too large

​Not found

​Task failed

​Task error codes

​SDK-specific errors