Errors

Two different things fail, and they look nothing alike. A request error rejects the call before anything is queued, with a 4xx or 5xx right away. A task failure happens after a 201: the task runs and the work fails seconds or minutes later.

POST /image/generate
  │
  ├─ rejected   4xx / 5xx   { "code": "UNAUTHORIZED", "message": "..." }
  │                         nothing queued, held, or charged
  │
  └─ 201 { taskId } ──▶ task runs ──┬─▶ completed   items can still carry an error
                                     └─▶ failed      errors: [{ code, message? }]

Handle both.

Request errors#

The body is flat, with code at the top level in SCREAMING_SNAKE_CASE:

{ "code": "INSUFFICIENT_BALANCE", "message": "Insufficient balance." }

Branch on code, never on message. message is optional: TASK_NOT_FOUND, API_KEY_NOT_FOUND, INVALID_TOKEN, and TOKEN_EXPIRED have none. INSUFFICIENT_SCOPE and SCOPE_ESCALATION add a scopes object.

VALIDATION_ERROR covers the checks that run after the schema passed:

• metadata over 2048 bytes
• a destination name you don't own
• inputs or options the chosen model cannot take
• an upload with no files, more than 10 files, a file that is not JPEG, PNG, or WEBP, or a file under 1 KB or over 10 MB

A 429 other than SPENDING_LIMIT_EXCEEDED means back off and retry. There is no Retry-After header. Rate limits has the rest.

Schema rejections use a different shape#

A body that fails the schema never reaches the handler, so it gets no code. The validator answers 400 with its own shape, which depends on the endpoint:

{
  "data": { "model": "auto", "count": 1 },
  "error": [
    {
      "path": ["prompt"],
      "code": "required",
      "expected": "a string",
      "actual": "missing",
      "message": "prompt must be a string (was missing)"
    }
  ],
  "success": false
}

Read path and message on each issue. count outside 1 to 20, an unknown model id, and a missing prompt all fail here. data echoes the request body, so keep these responses out of logs you share.

Task failures#

An accepted task settles as completed or failed, and both can carry error codes. Where the code lands depends on the task type:

So a refused prompt on POST /image/generate gives you 201 at creation and a completed task whose only image failed. Checking status === "completed" is not enough. Walk the array.

{
  "status": "completed",
  "result": {
    "model": "black-forest-labs/flux.2-pro",
    "images": [
      {
        "status": "failed",
        "error": {
          "code": "RESTRICTED_CONTENT",
          "message": "The request was blocked by content moderation."
        }
      }
    ]
  }
}

An image.generate or video.generate task reaches failed only when the work around generation broke: resolving the model, the inputs, or the size (a _4k size on a model without 4k fails with CAPABILITY_NOT_SUPPORTED), queueing the task, or the daily sweep that expires a task stuck on pending.

Codes#

Before a retryable code reaches you, Mynth has already retried across providers: up to four attempts per image and three per video. See tasks. What RESTRICTED_CONTENT means is on prompts and images.

Webhooks carry the same values: .completed events carry result, and .failed events carry errors.

What is safe to retry#

• 400, 401, 403, 404, 409, 413, and 422 fail the same way every time. Fix the request.
• 429 SPENDING_LIMIT_EXCEEDED clears when the key's period rolls over.
• 502 DESTINATION_TEST_FAILED is your storage rejecting the upload. Fix the destination.
• 500 and connection failures are worth retrying, with one catch: there are no idempotency keys. Every create mints a new task and holds cost again, so resending a create that actually succeeded runs and charges it twice. If a create times out, check GET /tasks before sending it again.
• A create that fails while queueing marks its task failed with ENQUEUE_FAILED, releases the hold, and answers 500. Retrying that one is safe.
• A settled task never runs again. Retrying a task failure means a new request. Failed items are not charged.

In the SDK and CLI#

The SDK throws MynthAPIError for a request error, with status and code, and TaskAsync* errors while waiting on a task. SDK errors covers both, including why a schema rejection leaves code undefined.

The CLI prints the message to stderr and exits with a code scripts can branch on: 2 usage and VALIDATION_ERROR, 3 auth, 4 balance or spending limit, 5 RESTRICTED_CONTENT, 6 another 429, 1 anything else. CLI commands has the table.

Next steps#

• Tasks: statuses, partial failure, and attempts.
• Authentication: the auth codes in context.
• Webhooks: the same codes, pushed to you.