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:
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.
Do not build application logic around exact provider error sentences. Wording
can change without changing the failure class.
Recovery matrix
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.
- Persist the first returned
job_id.
- Poll that task through Get Task.
- Deduplicate callbacks and completed-task processing by
job_id.
- Use your own operation ID or database constraint so two workers cannot submit
the same user request.
- 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 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.
Email 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. 
