Errors

The error envelope, every status and code the API returns, what causes the common ones, 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"
  }
}

Two responses don’t use this envelope:

• Authentication failures return {"status": false, "error": "Unauthorized"} (401) or {"status": false, "error": "Forbidden"} (403). See Authentication.
• Request timeouts return 408 with {"error": "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.

Check whether error is an object before reading error.code.

Status codes

A resource in another organization returns 404, the same as one that doesn’t exist.

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 product 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

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:

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 product 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": {
      "product": "photo-to-clip",
      "reasons": ["..."]
    },
    "request_id": "59630881.e2a7f4"
  }
}

Check available and unavailable_reasons on GET /v1/workflows/products 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.

Failed jobs

A job that’s accepted and then fails doesn’t return an HTTP error; its status becomes failed and its error field holds one of a fixed set of messages, each ending Credits were released.:

• Generation failed upstream (HTTP <status>). Credits were released.
• Generation failed: the model backend is unavailable. Credits were released.
• Generation failed: the model backend could not complete the request. Credits were released.
• Generation failed: the model returned no output. Credits were released.
• Generation failed due to an internal error. Credits were released.

A failed product run’s error is the failing step’s key followed by its reason, for example clip: Generation failed upstream (HTTP 500). Credits were released. See failure messages for what each one means.

Retrying

There are no idempotency keys, so retry decisions depend on the request:

By status:

If a submit 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.