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

# Errors & recovery

> Decide whether to fix, wait, retry, or escalate a Legnext API failure.

Legnext failures occur either while a request is submitted or after an
asynchronous task has been accepted. Handle those stages differently.

## Read the failure

Task endpoints return the `TaskResponse` shape for both accepted and rejected
requests. A failure includes:

```json theme={null}
{
  "job_id": "4de9c4db-31e1-43df-a2bd-d54285ce4f39",
  "status": "failed",
  "error": {
    "code": 400,
    "message": "Human-readable failure",
    "raw_message": "Optional provider detail",
    "detail": null
  }
}
```

Use `error.code` and the HTTP status for broad control flow. Use `message` for
diagnostics and derive a safe user-facing summary in your application. Keep
`raw_message` in restricted server logs; it may contain untranslated or
provider-specific details.

<Warning>
  Do not build application logic around exact provider error sentences. Wording
  can change without changing the failure class.
</Warning>

## Recovery matrix

| Signal                                             | Meaning                                                                             | Client action                                                |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `400`                                              | Invalid field, unsupported parameter, incompatible model/action, or moderated input | Fix the request or source image; do not retry unchanged      |
| `401`                                              | Missing, invalid, or revoked API key                                                | Correct or replace the key                                   |
| `402`                                              | Insufficient quota                                                                  | Ask the user to top up, then submit a new task               |
| `403`                                              | Disabled/restricted account, moderation rejection, or daily error limit             | Correct the cause or contact support; do not retry unchanged |
| `404` from Get Task                                | Unknown or expired capability URL                                                   | Check the `job_id`; the task lookup window may have expired  |
| `429`                                              | Concurrency or staged-queue limit reached                                           | Wait for running tasks to finish, then retry with backoff    |
| transient `5xx` or network failure                 | Temporary Legnext or provider failure                                               | Retry with capped exponential backoff and jitter             |
| persistent `5xx` across attempts or unrelated jobs | Service incident                                                                    | Stop retrying and contact support with the `job_id`          |
| task `status: failed`                              | Background processing ended unsuccessfully                                          | Classify `error`; resubmit only when the class is retryable  |

## Submission and task failures

### The submit request was rejected

When the HTTP response is not successful, the request did not enter the normal
asynchronous lifecycle. Read the response body before deciding what to do.

* For `400`–`403`, change the input, credentials, account state, or balance.
* For `429`, wait for existing work to finish.
* For a transient `5xx`, use a bounded retry policy.

If a response already contains a `job_id`, persist it and query that task rather
than creating a replacement.

### The accepted task later failed

A submit can return successfully and the task can later reach
`status: failed`. Read `error.message` and `error.raw_message`, then classify the
failure:

* moderation, invalid parameters, and unsupported follow-up actions require a
  changed request;
* timeouts, provider rate limits, and generic execution failures may be retried
  as a new task;
* repeated failures for the same valid request should be escalated.

Failed tasks are terminal. Do not keep polling them.

## Retry without creating accidental jobs

Legnext does not provide a submit idempotency key and does not deduplicate by
prompt. Every repeated POST can create another billable task.

1. Persist the first returned `job_id`.
2. Poll that task through [Get Task](/api-reference/task-management/get-task).
3. Deduplicate callbacks and completed-task processing by `job_id`.
4. Use your own operation ID or database constraint so two workers cannot submit
   the same user request.
5. Retry a submit only when no `job_id` was returned and accepting a possible
   duplicate is preferable to dropping the request.

An internal task status of `retry` means Legnext is already resubmitting after a
transient provider failure. Keep waiting; do not submit a second task.

## Common non-retryable corrections

* Check the generated request schema for missing fields and enum values.
* Use the [image parameter matrix](/getting-started/image-parameters) for
  version-specific Midjourney flags.
* Pin `--v 6.1` when using legacy Character Reference (`--cref`); the API
  default is V7.
* Remove unsupported flags named by a `400` response.
* For a rejected follow-up action, choose another source image or regenerate the
  base image. `available_actions` is advisory, not a guarantee.
* For moderation failures, change the prompt or referenced image instead of
  repeatedly submitting the same content.

## When to contact support

Email [support@legnext.ai](mailto:support@legnext.ai) after a bounded retry
schedule when:

* multiple unrelated valid tasks fail with `5xx`;
* the same request fails repeatedly without an actionable validation message;
* credits appear inconsistent after the task reaches a terminal state; or
* a task remains non-terminal beyond your operational timeout.

Include the `job_id`, endpoint, UTC timestamp, HTTP status, and sanitized error
object. Never send the API key.