
A task-status request can return HTTP 200 while reporting a failed generation because the GET successfully retrieved the task record. The generation outcome lives in data.status, with related detail in data.error and data.usage.state. Checking only response.ok confuses successful retrieval with successful media creation.
This distinction applies to both images and video in the Imagild API. A readable error record is useful evidence; it should produce a clear failed-task view rather than a broken download or an endless spinner.
Key Takeaways
- Check the HTTP response first, then validate the task record and its status.
- Inspect billing state separately instead of assuming every 200 response consumed points.
- Treat unfamiliar or malformed data as a contract problem, not as success.
Read the two layers in order
MDN's explanation of HTTP 200 notes that a successful GET retrieves a resource in its response body. When that resource is a task record, the body can truthfully describe an unsuccessful generation.
A failed image record can therefore contain the following selected fields:
{
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"status": "failed",
"usage": {"points": 10, "state": "released"},
"error": {"code": "IMAGE_GENERATION_FAILED"}
}
}
This is a reduced illustrative response, not a real task to query. The ten points describe the task's quote; released describes its reservation outcome. Do not label that number as a new charge just because it is present.
Classify JSON before rendering a result
The following server-side function handles an already received fetch Response. It performs no generation or download. Your caller supplies the expected saved task ID.
async function classifyTaskResponse(response, expectedId) {
const payload = await response.json();
if (!response.ok) {
return { view: "access-or-read-error",
http: response.status, error: payload.error };
}
const task = payload.data;
if (!task || task.id !== expectedId ||
typeof task.status !== "string" ||
typeof task.usage?.state !== "string") {
return { view: "contract-error" };
}
if (task.status === "succeeded") {
return { view: task.output_url ? "download-ready"
: "output-contract-error", task };
}
if (task.status === "failed") return { view: "failed", task };
if (task.status === "unknown") return { view: "needs-review", task };
if (["initializing", "submitting", "queued", "processing"]
.includes(task.status)) {
return { view: "waiting", task };
}
return { view: "unrecognized-status", task };
}
Catch JSON parsing and network errors around this function. They indicate that the reader lacks a usable observation, so retain the last remote status rather than overwriting it with a failure.
Keep task errors distinct from request errors
A rejected GET uses a top-level error response and an HTTP error status. For example, an expired key can produce 401 and inactive membership can produce a membership-related 403. These tell you why the task could not be read.
A generation failure appears inside an accessible task's data.error. The current image and video failure codes are IMAGE_GENERATION_FAILED and VIDEO_GENERATION_FAILED. An unknown video outcome uses UPSTREAM_RESULT_UNKNOWN, which calls for reconciliation rather than a new paid retry.
Replicate's prediction-state reference is another example of exposing generation outcomes as resource state. Its exact states and billing rules should not be copied into an Imagild parser.
Test the renderer with distinct fixtures
Build a small local fixture set: HTTP 200 with succeeded, HTTP 200 with failed and released usage, HTTP 200 with unknown and reserved usage, and HTTP 403 with a top-level membership error. Confirm that each gets a different next action.
The failed case should show the safe code and usage state without enabling content download. If billing appears inconsistent with the reported outcome, retain the evidence and request review rather than modifying an account balance locally.
Use the failed-job next-action checklist for diagnostic context. If a supposed image download contains a page, follow the HTML payload check. A status-aware client avoids turning a readable failure into an incorrect success message.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- Why Does My Downloaded Image Open as a Web Page?
Sources and scope
- Imagild API console and integration guide: Current Imagild entry point, active-member access, asynchronous task reading and authenticated output contract; implementation facts cross-checked in lib/relay and the 2026-10-28 claims manifest.
- Replicate Prediction Lifecycle: General distinction between an ongoing prediction and its reported outcome. Its provider deadlines, cancellation, billing and retention rules are not attributed to Imagild.
- MDN HTTP 200 OK: For GET, HTTP 200 can indicate successful resource retrieval; the retrieved task resource still needs application-level outcome interpretation.
Product instructions were checked against the current Imagild API contract and the public model catalog. Code, budgets and acceptance checks are illustrative; this article does not claim a new paid generation test, an uptime measurement, a search-volume study or a ranking of AI citations.
Prepared by Imagild Editorial, the company editorial team responsible for these guides. AI assisted research and drafting. This is documentation-based guidance with proposed examples, not a claim of hands-on testing or an independent product review. Report a correction.
Cover: Original Imagild product screenshot captured on 28 October 2026; model availability and prices may change. This image is not an API response or a performance benchmark.