Windpaint
Overview

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"
  }
}
error.codestringrequired

Stable, machine-readable reason, named domain.reason. Branch on this.

error.messagestringrequired

Human-readable description, safe to show a user. The wording can change; don’t parse it.

error.detailsobject

Structured specifics, such as the field that failed or the amounts involved. Omitted when there’s nothing to add.

error.request_idstring

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 408 with {"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

StatuscodeMeaning
400request.validation_failedThe body doesn’t match the endpoint’s schema: wrong type, missing required field, or unknown field.
400request.bad_requestThe request is malformed, for example invalid JSON or a bad query parameter.
400request.organization_requiredThe endpoint needs an organization and the caller has none, for example a user who hasn’t joined one yet.
401auth.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.
402billing.insufficient_creditsYour available credits don’t cover the job or run.
403auth.missing_scope (auth body), auth.forbiddenYour key’s role lacks the permission, or you tried to grant more access than you hold.
404request.not_found, api_key.not_found, webhook.not_found, role.not_foundThe resource doesn’t exist in your organization, or the route doesn’t exist.
405request.method_not_allowedThe route exists but not for this HTTP method.
408request.timeout (timeout body)The request took longer than the route’s time limit. The message says how long that is.
409request.conflictThe request conflicts with current state: a taken slug, an archived project, the default project, a job that hasn’t finished.
409generation.asset_in_useYou tried to delete an asset that a queued or running job uses as an input.
409idempotency.key_reused, idempotency.in_progressAn Idempotency-Key was reused with a different request, or its first request is still running. See Idempotency.
410generation.asset_goneThe asset’s file was deleted or has expired. See Asset retention.
413request.bad_requestThe request body is too large: over 32 MiB for a submit, or over 200 MiB plus multipart framing for an upload.
422request.validation_failedThe body is well-formed but breaks a rule: an unsupported resolution, a missing prompt, an input asset from another project.
422input.invalid, input.unsupported_format, input.too_large, input.dimensions, input.duration, input.fetch_failedAn uploaded file or an input URL or data URI was rejected. See Inputs.
422generation.asset_goneAn input asset has expired or was deleted. details has slot and asset_ids (input and asset_id for workflow runs).
422moderation.input_blockedThe prompt or an input image was blocked by content moderation. See Content moderation.
422idempotency.key_invalidThe Idempotency-Key header is empty or longer than 255 characters.
422webhook.unknown_events, webhook.invalid_url, webhook.insecure_urlA webhook’s event names or URL were rejected. See Webhooks.
429rate_limit.requests, rate_limit.concurrencyYou’re over a requests-per-minute or submits-per-minute limit, or at your concurrent job limit. See Rate limits.
500request.internal_errorSomething failed on Windpaint’s side. The message is generic; quote request_id to support.
501request.not_implementedThe operation exists but isn’t built for this kind of resource yet.
503request.service_unavailable, billing.not_configuredA 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

MessageCauseWhat 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:

MessageWhat 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 as Generation 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.

CodeUsual statusRetryableMeaningWhat to do
job.capacity_unavailablefailedYesNo 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.timeoutfailedYesThe model backend didn’t answer in time.Retry. For video, a shorter duration or lower resolution finishes faster.
job.provider_errorfailedYesThe 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_invalidfailedNoThe 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_missingfailedYesThe model reported success but returned no usable output.Retry.
job.model_unavailablefailedNoThe model stopped offering the capability between submit and run.Pick another model from GET /v1/generation/models.
job.internalfailedYesWindpaint 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_usercanceledNoThe 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_workflowcanceledNoAnother 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_failedfailedNoA 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_blockednsfwNoThe 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_code is the code of the step that failed, and its error is that step’s key followed by its reason, for example clip: 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_failed or request.service_unavailable. These codes come from the status code table above, not from GET /v1/errors.
  • When a step fails, steps that were still pending or running become canceled with job.canceled_by_workflow.
  • Canceling a run marks the run and its unfinished steps and jobs canceled with job.canceled_by_user. Canceling one step’s job directly, through POST /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 failed with job.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:

Statuserror
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.

RequestSafe to retry?Notes
Any GETYesBack off on 5xx and network errors.
Status pollsYesPoll at 1 to 15 second intervals, or use the event stream.
POST .../cancelYesCanceling a finished job returns it unchanged.
PUT /v1/billing/settings, PATCH requestsYesThey set state; repeating gives the same result.
DELETE requestsYesDeleting again returns 204.
POST /v1/generation/estimate, workflow estimateYesRead-only.
POST /v1/generation/capabilities/{capability}, POST /v1/generation/models/{model}With Idempotency-KeyWithout a key, a retry creates and bills a second job.
POST /v1/workflows/{slug}/runsWith Idempotency-KeyWithout a key, a retry starts a second run.
POST /v1/generation/uploadsYesUploads are free. Without a key, a retry creates a duplicate asset.
POST /v1/projects, POST /v1/api-keys, POST /v1/webhooksNoCreates a duplicate key or webhook; a duplicate project gets 409.
POST /v1/billing/topupsYesEach call opens a new checkout; only completed checkouts charge.

By status:

StatusRetry?
400, 401, 403, 404, 405, 410, 413, 422No. Fix the request.
409Only for idempotency.in_progress: wait Retry-After and send the same request with the same key. Otherwise fix the request.
402After topping up or once running jobs settle.
429Yes, after Retry-After seconds. See Rate limits.
408, 500, network errorGETs, 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.
503Yes, 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.