Errors
The error envelope, every status and code the API returns, the error codes of failed jobs, and which requests are safe to retry.
Errors use standard HTTP status codes and one JSON envelope:
{
"error": {
"code": "billing.insufficient_credits",
"message": "Not enough credits: this needs 4.00 and 1.20 are available.",
"details": { "required": "4.00", "available": "1.20" },
"request_id": "59630881.7c2e4a"
}
}
Stable, machine-readable reason, named domain.reason. Branch on this.
Human-readable description, safe to show a user. The wording can change; don’t parse it.
Structured specifics, such as the field that failed or the amounts involved. Omitted when there’s nothing to add.
Identifies the request in Windpaint’s logs. Include it when you contact support. It’s only in the body; there’s no request id header.
Two responses don’t use this envelope, but both carry a top-level code:
- Authentication failures return
{"status": false, "error": "Unauthorized", "code": "auth.invalid_token", "message": "...", "request_id": "..."}(401) or the same with"error": "Forbidden"(403). See Authentication. - Request timeouts return
408with{"error": "Request timeout", "code": "request.timeout", "message": "Request took longer than <n> seconds to process"}, where<n>is the limit that applied: 120 for uploads, a few seconds for other routes.
If error is an object, read error.code; if it’s a string, read the top-level code.
Status codes
| Status | code | Meaning |
|---|---|---|
400 | request.validation_failed | The body doesn’t match the endpoint’s schema: wrong type, missing required field, or unknown field. |
400 | request.bad_request | The request is malformed, for example invalid JSON or a bad query parameter. |
400 | request.organization_required | The endpoint needs an organization and the caller has none, for example a user who hasn’t joined one yet. |
401 | auth.unauthenticated, auth.invalid_token, auth.account_disabled, auth.account_pending_approval (auth body) | No credential; an invalid, revoked or expired API key; a disabled account; or an account still waiting for approval. |
402 | billing.insufficient_credits | Your available credits don’t cover the job or run. |
403 | auth.missing_scope (auth body), auth.forbidden | Your key’s role lacks the permission, or you tried to grant more access than you hold. |
404 | request.not_found, api_key.not_found, webhook.not_found, role.not_found | The resource doesn’t exist in your organization, or the route doesn’t exist. |
405 | request.method_not_allowed | The route exists but not for this HTTP method. |
408 | request.timeout (timeout body) | The request took longer than the route’s time limit. The message says how long that is. |
409 | request.conflict | The request conflicts with current state: a taken slug, an archived project, the default project, a job that hasn’t finished. |
409 | generation.asset_in_use | You tried to delete an asset that a queued or running job uses as an input. |
409 | idempotency.key_reused, idempotency.in_progress | An Idempotency-Key was reused with a different request, or its first request is still running. See Idempotency. |
410 | generation.asset_gone | The asset’s file was deleted or has expired. See Asset retention. |
413 | request.bad_request | The request body is too large: over 32 MiB for a submit, or over 200 MiB plus multipart framing for an upload. |
422 | request.validation_failed | The body is well-formed but breaks a rule: an unsupported resolution, a missing prompt, an input asset from another project. |
422 | input.invalid, input.unsupported_format, input.too_large, input.dimensions, input.duration, input.fetch_failed | An uploaded file or an input URL or data URI was rejected. See Inputs. |
422 | generation.asset_gone | An input asset has expired or was deleted. details has slot and asset_ids (input and asset_id for workflow runs). |
422 | moderation.input_blocked | The prompt or an input image was blocked by content moderation. See Content moderation. |
422 | idempotency.key_invalid | The Idempotency-Key header is empty or longer than 255 characters. |
422 | webhook.unknown_events, webhook.invalid_url, webhook.insecure_url | A webhook’s event names or URL were rejected. See Webhooks. |
429 | rate_limit.requests, rate_limit.concurrency | You’re over a requests-per-minute or submits-per-minute limit, or at your concurrent job limit. See Rate limits. |
500 | request.internal_error | Something failed on Windpaint’s side. The message is generic; quote request_id to support. |
501 | request.not_implemented | The operation exists but isn’t built for this kind of resource yet. |
503 | request.service_unavailable, billing.not_configured | A model, workflow or the payment provider isn’t available right now. |
A resource in another organization returns 404, the same as one that doesn’t exist. Other framework-level errors use a code for their status: 404 request.not_found, 409 request.conflict, 429 request.rate_limited, 503 request.service_unavailable; any other 4xx is request.bad_request and any other 5xx is request.internal_error.
Common errors
400: schema validation
The body failed type checking. details.errors lists each problem with the field (key) and where it was (source):
{
"error": {
"code": "request.validation_failed",
"message": "Validation failed for POST /v1/projects",
"details": {
"errors": [
{ "message": "Expected `str | null`, got `int`", "key": "slug", "source": "body" }
]
},
"request_id": "59630881.1f9a0b"
}
}
A field the endpoint doesn’t accept is reported as Object contains unknown field `foo` . Fix the request; retrying won’t help.
402: insufficient credits
{
"error": {
"code": "billing.insufficient_credits",
"message": "Not enough credits: this needs 4.00 and 1.20 are available.",
"details": { "required": "4.00", "available": "1.20" },
"request_id": "59630881.7c2e4a"
}
}
required is the job’s price (or a workflow run’s estimate) and available is your spendable balance, both as decimal strings. Nothing was created or charged. Top up (see Billing) or wait for running jobs to release their holds, then submit again. Credits held by running jobs aren’t available, so a burst of submits can hit 402 before your balance looks empty.
409: conflict
| Message | Cause | What to do |
|---|---|---|
A project with this slug already exists. | Creating or renaming a project to a slug that’s taken. details.slug names it. | Pick another slug. A slug derived from the name can collide too; pass slug explicitly. |
The project is archived. | Writing (submit, upload, run) into an archived project. details.project_id names it. | Use another project. Archiving can’t be undone. |
The default project cannot be archived. | Archiving the project with is_default: true. | Nothing; the default project stays. |
422: invalid inputs
422 means the request was well-formed but Windpaint can’t do what it asks. The message says exactly what’s wrong. Common ones from generation:
| Message | What to do |
|---|---|
prompt is required. | Send a non-empty prompt for capabilities that need one. |
No model implements image.edit yet. | The capability is defined but has no model. Check GET /v1/generation/capabilities for models: []. |
Unknown model 'x'. Known: ... | Use a model id from GET /v1/generation/models. The list in the message holds the same models. |
Image inputs may be at most 20 MB. (input.too_large) | Use a smaller file. Limits per kind are in Inputs. |
flux-2-klein-4b resolution must be one of 1k. | Use a resolution the model lists. |
aspect_ratio must be one of 1:1, 4:3, ... | Use a listed aspect ratio. |
z-image-turbo has no quality setting. | Drop quality. No model takes it today. |
wan-2.2-i2v duration must be one of 5 seconds. | Use a listed duration, or omit it. (Video is coming soon.) |
video.generate on wan-2.2-i2v: slot 'start_frame' takes 1 asset(s); got 0. | Fill each input slot with the number of assets the model needs. |
Inputs must be asset ids, asset URLs returned by /v1/generation, public https URLs or data: URIs. (input.invalid) | Pass an asset id, an asset URL, an https:// URL or a data: URI. details.value holds what you sent. |
Could not fetch input URL: <reason> (input.fetch_failed) | Windpaint couldn’t download an input URL. details.reason says why, for example the server answered HTTP 404. |
Input asset not found in this project. | The asset is in another project, or doesn’t exist. details.asset_ids lists them. |
Input slot 'start_frame' takes image assets. | The asset is the wrong kind for that slot. |
GIF is not a supported input format. Supported: ... (input.unsupported_format) | Convert the file to a supported format. details.allowed lists them. |
File is not a readable image. (input.unsupported_format) | The file’s bytes don’t decode as an image. |
The request was blocked by content moderation. (moderation.input_blocked) | Change the prompt or input images. details.categories says what was flagged. |
Outside generation: name is required. and the slug format message on projects, A top-up must be between 100 and 100000 credits. on top-ups, and low_balance_threshold cannot be negative. on billing settings.
503: unavailable
A model that can’t run right now:
{
"error": {
"code": "request.service_unavailable",
"message": "wan-2.2-i2v is not available on this deployment.",
"details": { "model": "wan-2.2-i2v" },
"request_id": "59630881.d40c11"
}
}
The same code with "... has no price for this tier and cannot be run." means the model has no price for the resolution or duration you asked for; details names the capability, model, resolution and duration. Try another tier, or check available and prices in GET /v1/generation/models.
A workflow that can’t run reports why in details.reasons:
{
"error": {
"code": "request.service_unavailable",
"message": "photo-to-clip cannot run on this deployment yet.",
"details": {
"workflow": "photo-to-clip",
"reasons": ["..."]
},
"request_id": "59630881.e2a7f4"
}
}
Check available and unavailable_reasons on GET /v1/workflows before starting a run.
details only names the model. Pick another model from GET /v1/generation/models, or try again later.
On POST /v1/billing/topups, 503 means the payment provider couldn’t start checkout. Nothing was charged; try again shortly.
Job error codes
A job that’s accepted and later doesn’t produce output doesn’t return an HTTP error. Its status becomes failed, nsfw or canceled, and two fields say why:
error_code: a stable code from the table below. Branch on this.error: a human-readable message, such asGeneration failed upstream (HTTP 500). Credits were released.The wording can change.
error_code is on the request status (including the cancel response and the job webhook), on each workflow run step and on the run, and on items in GET /v1/activities. It’s null while a job is queued or running and when it completes, and always set when it ends failed, nsfw or canceled, including jobs that finished before the field existed.
| Code | Usual status | Retryable | Meaning | What to do |
|---|---|---|---|---|
job.capacity_unavailable | failed | Yes | No model backend could take the job: none was serving the model, or every one stayed at capacity through all retries and fallbacks. | Retry with backoff. Check available on GET /v1/generation/models, or pick another model. |
job.timeout | failed | Yes | The model backend didn’t answer in time. | Retry. For video, a shorter duration or lower resolution finishes faster. |
job.provider_error | failed | Yes | The model backend took the job and failed it, for a reason that doesn’t point at your inputs. | Retry once. If it repeats, contact support with the request id. |
job.input_invalid | failed | No | The model rejected the inputs: an unsupported reference image type, an empty file, or a missing or unsupported frame. | Change the inputs. Reference images must be PNG, JPEG or WebP. |
job.output_missing | failed | Yes | The model reported success but returned no usable output. | Retry. |
job.model_unavailable | failed | No | The model stopped offering the capability between submit and run. | Pick another model from GET /v1/generation/models. |
job.internal | failed | Yes | Windpaint failed while running the job, for example while reading inputs or storing outputs. | Retry. If it repeats, contact support with the request id. |
job.canceled_by_user | canceled | No | The job, or the workflow run it belonged to, was canceled through its cancel endpoint. | Nothing. Submit again if the cancel was unintended. |
job.canceled_by_workflow | canceled | No | Another step of the same workflow run failed, so this step was canceled before it finished. | Read the run’s error_code for the step that failed. |
workflow.op_failed | failed | No | A local processing step of a workflow run (resize, crop, frame extraction, concatenation) rejected its input. | Change the run’s inputs. The step’s error says what it couldn’t handle. |
moderation.output_blocked | nsfw | No | The output was blocked by content moderation, or the model refused the job on content grounds. No output is kept. | Change the prompt or inputs. See Content moderation. |
“Usual status” is the status a code normally comes with, not a guarantee. “Retryable” means submitting the same request again can succeed.
The same catalog is available from the API, without authentication:
curl https://api.windpaint.ai/v1/errors
{
"errors": [
{
"code": "job.timeout",
"status": "failed",
"retryable": true,
"description": "The provider did not answer within the time limit, or answered HTTP 408 or 504.",
"fix": "Retry. For video, a shorter duration or lower resolution finishes faster."
}
]
}
Workflow runs
- A failed run’s
error_codeis the code of the step that failed, and itserroris that step’s key followed by its reason, for exampleclip: Generation failed upstream (HTTP 500). Credits were released. - A step that couldn’t be submitted (no price, not enough credits, invalid inputs, model unavailable) carries the HTTP error code it was refused with, such as
billing.insufficient_credits,request.validation_failedorrequest.service_unavailable. These codes come from the status code table above, not fromGET /v1/errors. - When a step fails, steps that were still pending or running become
canceledwithjob.canceled_by_workflow. - Canceling a run marks the run and its unfinished steps and jobs
canceledwithjob.canceled_by_user. Canceling one step’s job directly, throughPOST /v1/generation/requests/{id}/cancel, fails that step and the run (failed,job.canceled_by_user). - A step whose job can no longer be found reports
failedwithjob.internal.
Messages
error stays a human-readable message. For failed jobs it’s one of the failure messages. Jobs that end another way now have one too:
| Status | error |
|---|---|
nsfw (blocked by Windpaint’s moderation) | The output was blocked by content moderation. Credits were released. |
nsfw (the model refused the content) | Generation blocked: the provider refused the content. Credits were released. |
canceled (by you) | Canceled before it finished. Credits were released. |
canceled (a sibling step failed) | Canceled because another step of the run failed. Credits were released. |
Retrying
Submits, uploads and workflow runs accept an Idempotency-Key header. With one, a retry returns the original response instead of creating a second job, so those requests are safe to retry. Without one, they aren’t.
| Request | Safe to retry? | Notes |
|---|---|---|
Any GET | Yes | Back off on 5xx and network errors. |
| Status polls | Yes | Poll at 1 to 15 second intervals, or use the event stream. |
POST .../cancel | Yes | Canceling a finished job returns it unchanged. |
PUT /v1/billing/settings, PATCH requests | Yes | They set state; repeating gives the same result. |
DELETE requests | Yes | Deleting again returns 204. |
POST /v1/generation/estimate, workflow estimate | Yes | Read-only. |
POST /v1/generation/capabilities/{capability}, POST /v1/generation/models/{model} | With Idempotency-Key | Without a key, a retry creates and bills a second job. |
POST /v1/workflows/{slug}/runs | With Idempotency-Key | Without a key, a retry starts a second run. |
POST /v1/generation/uploads | Yes | Uploads are free. Without a key, a retry creates a duplicate asset. |
POST /v1/projects, POST /v1/api-keys, POST /v1/webhooks | No | Creates a duplicate key or webhook; a duplicate project gets 409. |
POST /v1/billing/topups | Yes | Each call opens a new checkout; only completed checkouts charge. |
By status:
| Status | Retry? |
|---|---|
400, 401, 403, 404, 405, 410, 413, 422 | No. Fix the request. |
409 | Only for idempotency.in_progress: wait Retry-After and send the same request with the same key. Otherwise fix the request. |
402 | After topping up or once running jobs settle. |
429 | Yes, after Retry-After seconds. See Rate limits. |
408, 500, network error | GETs, yes. Submits and runs, yes if you sent an Idempotency-Key; otherwise list recent jobs or runs first, because the request may have gone through. |
503 | Yes, with backoff, for payment errors. For an unavailable model or workflow, not until it’s available. |
If a submit without an Idempotency-Key fails with a timeout or a dropped connection, check GET /v1/generation/requests?limit=10 (or GET /v1/workflows/runs?limit=10) for a job created in the last few seconds with your prompt before submitting again.