---
title: Errors | Runware Docs
url: https://runware.ai/docs/serverless/errors
description: Every failure the Serverless API returns, how to recognize it, and what to do about it.
relatedDocuments:
  - https://runware.ai/docs/serverless/troubleshooting
  - https://runware.ai/docs/serverless/invoking
  - https://runware.ai/docs/serverless/monitoring
---
## Introduction

Every error the Serverless API returns is an **RFC 9457 problem document**, served as `application/problem+json`.

```json
{
  "type": "https://docs.runware.ai/serverless/errors#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "app does not declare endpoint \"does-not-exist\"",
  "endpointPath": "does-not-exist",
  "requestId": "..."
}
```

**Switch on `type` and on the extension members, never on `detail`.** The `type` URL is stable and points at the section of this page that explains it. The `detail` string is written for a human reading a log and can change.

Keep the `requestId`. It is what support needs to find your request.

## Recognizing each failure

**Every status the API returns has a row here**, and a status that two conditions share has a row each, because the extension members are what tell those apart.

<table><tbody><tr><td>Status</td><td>Condition</td><td>How to recognize it</td></tr><tr><td><code>400</code></td><td>The body is malformed JSON</td><td>Title <code>Bad Request</code>, and no <code>errors</code> array</td></tr><tr><td><code>401</code></td><td>The request had no API key, or one the platform rejects</td><td><code>type</code> ends in <code>#unauthorized</code></td></tr><tr><td><code>402</code></td><td>Your organization's credit balance cannot cover the capacity a create, deploy, resume or scaling change would start</td><td><code>type</code> ends in <code>#insufficient-credit</code>, and <code>shortfall</code> is present</td></tr><tr><td><code>402</code></td><td>Your organization's credit is suspended after a refund of credit already spent</td><td><code>type</code> ends in <code>#credit-suspended</code>, and <code>shortfall</code> is present</td></tr><tr><td><code>403</code></td><td>Your organization has no Serverless access, or it was revoked</td><td><code>type</code> ends in <code>#forbidden</code>. Distinct from an app that does not exist</td></tr><tr><td><code>404</code></td><td>The app does not declare that endpoint</td><td><code>endpointPath</code> is present and gives the rejected path</td></tr><tr><td><code>404</code></td><td>The app does not exist, or was deleted</td><td>No <code>endpointPath</code> member</td></tr><tr><td><code>405</code></td><td>The path exists but does not serve this method</td><td><code>type</code> ends in <code>#method-not-allowed</code>, and an <code>Allow</code> header lists the methods it serves</td></tr><tr><td><code>412</code></td><td>The resource changed since the <code>ETag</code> you sent</td><td><code>type</code> ends in <code>#precondition-failed</code></td></tr><tr><td><code>413</code></td><td>The body is bigger than the route accepts</td><td><code>type</code> ends in <code>#request-entity-too-large</code>, and <code>detail</code> gives the limit in bytes</td></tr><tr><td><code>409</code></td><td>The app is stopped, deleting or failed</td><td>Title <code>Conflict</code>, and no <code>source-upload-</code> type</td></tr><tr><td><code>409</code></td><td>A source upload cannot move the way you asked</td><td><code>type</code> ends in one of the <code>#source-upload-</code> forms below</td></tr><tr><td><code>409</code></td><td>The request would take the environment past its worker or GPU cap</td><td><code>type</code> ends in <code>#environment-cap-reached</code>, and <code>detail</code> gives the cap, what the environment has and what the request adds</td></tr><tr><td><code>409</code></td><td>The environment is paused and the request would add capacity</td><td><code>type</code> ends in <code>#environment-paused</code></td></tr><tr><td><code>415</code></td><td>The body's Content-Type is not one the operation declares, or the body has none</td><td><code>type</code> ends in <code>#unsupported-media-type</code></td></tr><tr><td><code>422</code></td><td>The body violates the endpoint's schema</td><td><code>errors</code> array, one entry per field, each with a JSON Pointer such as <code>/payload/image</code></td></tr><tr><td><code>422</code></td><td>A path or query parameter breaks its rule, for example <code>limit=0</code></td><td><code>errors</code> entries give the parameter in <code>detail</code> and have no <code>pointer</code></td></tr><tr><td><code>422</code></td><td>The archive you uploaded breaks an archive rule</td><td><code>type</code> ends in <code>#code-zip-invalid</code> or <code>#container-zip-invalid</code></td></tr><tr><td><code>429</code></td><td>The organization's read allowance for logs, metrics and request errors is spent</td><td><code>Retry-After</code> header, and <code>type</code> does not end in <code>#environment-paused</code></td></tr><tr><td><code>429</code></td><td>The environment is paused and you invoked an app in it</td><td><code>type</code> ends in <code>#environment-paused</code>, and there is no <code>Retry-After</code></td></tr><tr><td><code>503</code></td><td>The platform has no GPUs to place your workers</td><td><code>type</code> ends in <code>#capacity-unavailable</code>, with a <code>Retry-After</code></td></tr><tr><td><code>503</code></td><td>Something the route depends on is unreachable, or the tenancy is still provisioning</td><td>Title <code>Service Unavailable</code> and no <code>Retry-After</code></td></tr><tr><td><code>500</code></td><td>The platform could not complete the request and no narrower answer fits</td><td><code>type</code> ends in <code>#internal-server-error</code></td></tr><tr><td><code>501</code></td><td>An OIDC connector write on a platform that has no OIDC issuer</td><td><code>type</code> ends in <code>#not-implemented</code></td></tr><tr><td><code>502</code></td><td>A service this route depends on was unreachable or refused the request</td><td><code>type</code> ends in <code>#bad-gateway</code></td></tr><tr><td><code>504</code></td><td>The platform waited as long as it will wait and gave up</td><td><code>type</code> ends in <code>#gateway-timeout</code></td></tr></tbody></table>

## Bad request

`400` means **the platform could not parse the request**, most often a malformed JSON body. The response omits the `errors` array, because the platform never validated any field.

A request the platform can read but that breaks a rule returns [`422`](#unprocessable-entity). `400` means the body could not be read, `422` means it was read and it is wrong.

A log tail query the platform refuses also returns `400`. **Change the query**, because the same request returns the same `400` on every retry.

### Container config yaml invalid

The `container.yaml` beside your Dockerfile is not valid YAML, so the platform never checked the document's own rules. **`detail` gives the position where the parser stopped**, as in `/endpoints/0: mapping keys must be strings`.

This is the one container config failure that returns `400`. Every other one returns [`422`](#unprocessable-entity), because a `422` reports a field and here the platform parsed nothing.

## Unauthorized

`401` means **the request has no API key, or the platform rejects the key**. The key identifies your organization, so check the `Authorization` header.

A key that is valid but belongs to an organization without Serverless access is a [`403`](#forbidden), not a `401`.

## Payment required

`402` always means money instead of capacity, and it always includes `shortfall`, the amount to add. **Nothing is recorded when it is returned**, so the same request succeeds as sent once the balance is there.

Two types share the status, and they differ in how you got here.

### Insufficient credit

`402` with the `insufficient-credit` type means **your organization's credit balance cannot cover the GPU capacity the request would start**. It comes from creating an app, updating its source, deploying a version, resuming, or a configuration change that raises `minWorkers` or moves to another `gpuType`. Invocations never return it.

**Read `shortfall`, not `detail`.** It is the amount to add to your balance.

```json
{
  "type": "https://docs.runware.ai/serverless/errors#insufficient-credit",
  "title": "Payment Required",
  "status": 402,
  "detail": "credit balance is short 12.5 credits: capacity needs 20.0 in cover, 0.0 is held and 7.5 is available",
  "shortfall": { "amount": "12.5", "currency": "USD" },
  "requestId": "..."
}
```

An app that scales to zero **still needs credit for one worker**, because that is the smallest ceiling it can be deployed with. A configuration change that lowers or keeps capacity is never answered with a `402`, though the rollout it starts is checked again.

**The balance is checked again when a rollout starts**, so a build that finishes after the balance has fallen can still fail to roll out. The app's `error` event then says `insufficient credit`.

### Credit suspended

`402` with the `credit-suspended` type means **a refund took back credit your organization had already spent**, and the balance is below zero. Until a top-up brings it back to zero or above, **every request that starts capacity is refused**, including ones the balance covered before. `shortfall` is the top-up that lifts the suspension, and the request then succeeds as sent.

## Forbidden

`403` means **the credentials are good and the block is on the organization**: it has no Serverless access, or the access it had was revoked.

**It does not clear on its own.** That is the difference from a [`503`](#service-unavailable), which can look the same from the outside. A tenancy still being provisioned is retryable. One that was revoked or never existed is not.

## Not found

An unknown endpoint and a missing app **both return `404`**, and the `endpointPath` member is what separates them. When it is present, the path is what was rejected, not the app.

The path is **checked against the active version's endpoint set before anything is queued**, so an unknown endpoint never creates a task and never costs you anything.

```json
{
  "type": "https://docs.runware.ai/serverless/errors#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "app does not declare endpoint \"does-not-exist\"",
  "endpointPath": "does-not-exist"
}
```

## Method not allowed

`405` means **the path exists but does not serve the method you sent**, and the response includes an `Allow` header naming the methods it does serve. `DELETE /v1/app-summary` is answered this way, because that path serves `GET`.

A path that matches nothing is [`404`](#not-found) instead. **Both are decided before your credentials are read**, so neither of them says anything about your key.

## Conflict

`409` means the resource exists but **its current state cannot accept what you asked for**. A stopped app has released its workers, and a deleting or failed one is not coming back on its own. Deploy a version over a failed app to bring it back, because a stop is not accepted from `failed`.

**Resume a stopped app before invoking it.** An app still initializing its first version also returns `409`, and **that one clears by itself** once the build finishes.

**The upload flow uses the same status for its own states**, and each one has its own type. See [Source uploads](https://runware.ai/docs/serverless/api-source-uploads) for the flow they belong to.

**An [environment](https://runware.ai/docs/serverless/environments) refuses capacity with this status too**, either because the request crosses a cap or because the environment is paused. Invoking an app in a paused environment returns [`429`](#environment-paused) instead, since nothing about the app's own state is wrong.

### Environment cap reached

The request would take the environment past **the worker or GPU cap in force on it**, so it is refused before anything starts. The count is what the environment's other apps hold, each the larger of its live workers and its keep-warm floor, plus the workers this request starts and their GPUs. `detail` gives all three, as in `the environment's worker cap is 4; it holds 3 and this request adds 2`.

Every request that adds capacity is checked: creating an app, deploying a version, resuming a stopped one, and a configuration change that adds workers or restarts a failed app. **Lowering a cap below what is already running refuses the next deploy instead of stopping anything**, so stop or scale down another app, or raise the cap, and retry.

### Source upload incomplete

The session is open but **storage has no object for it yet**. Finish sending the archive to the transfer URL, then complete again.

### Source upload object changed

The staged object **was rewritten between being inspected and being read**. Nothing is judged on bytes that may be two different objects, so the session stays open: complete again once your writes have settled.

### Source upload rejected

Completion **already refused this archive**, and the reason it returns is the one it stored then. The object is not read a second time and its key is never reissued, so fix the archive and upload it under a new session.

### Source upload expired

The upload window closed. **This session can never become ready**, so open a new one.

### Source upload completed

The upload **already published its source**. Completing again returns that same source instead of creating a second one, and aborting is refused for the same reason: the source exists in its own right now.

### Source upload deleted

The upload was aborted. The record survives as a tombstone so its staging key is never reissued, and **the session itself is over**. Start a new session.

## Precondition failed

`412` means **the resource changed since the `ETag` you sent as `If-Match`**. The update was refused, and the resource still holds what the other writer left. Read it again, apply your change to the fresh state and retry with the new `ETag`.

`PUT /v1/oidc-connectors/{connectorName}` is the route that takes `If-Match`, and [`runware serverless connectors update`](https://runware.ai/docs/serverless/oidc-connectors) sends it for you. A malformed `If-Match` returns [`400`](#bad-request) before the connector is read, and one longer than 256 characters returns [`422`](#unprocessable-entity).

## Request entity too large

`413` means the request body is bigger than the route accepts, and `detail` gives the limit in bytes.

The limit is **10 MiB on `invoke-sync` and `invoke-async`**, whose body includes your endpoint's payload, and **1 MiB everywhere else**. An image or any other large input belongs behind a URL your handler fetches, not inside the payload.

The check runs **before validation**, so a body over the limit is refused without being parsed and you get this instead of a list of field violations.

## Unsupported media type

`415` means **the request body's `Content-Type` is not one the operation declares**. The body is never decoded, so this is neither malformed JSON ([`400`](#bad-request)) nor a schema failure ([`422`](#unprocessable-entity)).

**The detail separates the two cases.** A body sent under another type reads `Content-Type "text/plain" is not supported`, and a body sent with no type reads `Content-Type is required`.

`application/json` **with a charset parameter is still JSON**, so a body of that type that cannot be parsed is a `400`, and one that parses and breaks the schema is a `422`.

Four answers compete for the same request and **the order between them is fixed**. A failed credential wins everything and returns [`401`](#unauthorized), which says nothing about your body. A parameter that cannot be read comes next, so `?limit=nope` sent as `text/plain` is a `400` instead of this. Then the content type. Then the body against the schema.

## Unprocessable entity

A body that breaks the endpoint's schema returns `422` with **one entry per offending field**, each carrying a JSON Pointer to it. Read `errors` instead of parsing `detail`.

**The pointers are rooted at the whole body, not at your payload.** Your fields are under `payload` in the envelope, so a problem with `image` reads `/payload/image`.

```json
{
  "type": "https://docs.runware.ai/serverless/errors#unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "/payload/image: Field required; /payload/prompt: Extra inputs are not permitted",
  "errors": [
    { "pointer": "/payload/image", "detail": "Field required" },
    { "pointer": "/payload/prompt", "detail": "Extra inputs are not permitted" }
  ]
}
```

`Extra inputs are not permitted` means the field belongs to a different endpoint or to nothing. **A code app's endpoint schemas are closed**, so an unrecognized field is an error instead of something quietly dropped.

A container app declares its own schemas, and an endpoint that declares no `input` is a passthrough: it accepts whatever JSON you send and **never returns this error**. See [Bringing a container](https://runware.ai/docs/serverless/bringing-a-container).

Like a `404` on the path, **this happens before a worker is involved**.

A path or query parameter that breaks its rule, such as `limit` outside 1 to 100 on a listing, is a `422` too. **Its entry gives the parameter in `detail` and has no `pointer`**, because a query string is not a JSON document.

A `422` about a container's configuration includes a second pointer member, `configPointer`. In `container.yaml` it is the offending key. In the Dockerfile it is the line, written `/Dockerfile/line/{n}` with 1 as the first line. `pointer` is still the position of the archive in the request body, and an error about the archive itself includes only `pointer`, because nothing inside it was parsed.

### Code zip invalid

**The archive behind a `code` app broke an archive rule**: it could not be read, it had an unsafe entry path or a link, it had a duplicate name, it was oversized or a zip bomb, or its `modelFile` was missing or pointed outside the root.

### Container zip invalid

**The archive behind a `container` app broke an archive rule**: a required file missing or misnamed, an unsafe entry path, a link, or an oversized or bomb archive.

It is a **separate type from the code one on purpose**, so a client that can submit either source type knows which archive it got wrong.

### Base image unreadable

**The base image could not be pulled.** It does not exist, the registry refused it, the reference does not parse, the registry host does not resolve, or the reference points at the platform's own image registry.

`detail` reads `base-image-unreadable: <host>: <reference> could not be pulled`, with Docker Hub reported as `docker.io` because the pull talks to `index.docker.io`. Two endings carry the whole answer when they appear: `Private base images are not supported in this version`, which means a registry that answered `401` or `403`, and `Base images cannot come from the platform registry`. A code source adds one entry pointing at `/appSource/source/baseImage`.

**A registry that did not answer is a different failure**, a retryable [`503`](#service-unavailable) instead of this type. A base image that reads fine but has no `linux/amd64` build is a plain `422`, with a `detail` that opens `base-image-arch-unsupported:`.

### Container config unknown version

**`configVersion` gives a version of the document format the platform does not support.** See [Bringing a container](https://runware.ai/docs/serverless/bringing-a-container).

### Container config invalid

The document parsed and broke one of the document's own rules, most often a key that does not belong. `/endpoints/0/hardware: unknown field` is the common one, because **hardware is set on the app** instead of per endpoint.

### Container config duplicate endpoint

**Two entries in `endpoints` declare the same `path`.** A path identifies an endpoint on its own, so two rows on one path would leave no answer to which a request meant.

### Container config schema invalid

An endpoint's `input` or `output` is not a valid JSON Schema. **You write these yourself on the container path**, where a code app derives them from a handler signature instead.

### Container config too large

The `container.yaml` exceeds what the platform accepts, either the document itself or the **200 properties** counted across every `input` and `output` together.

### Container config reserved port

**`port` is one of the ports the platform's own containers hold.** Pick anything outside that set, listed in [Bringing a container](https://runware.ai/docs/serverless/bringing-a-container).

### Secret not found

**An attachment named a secret the environment has no `active` secret for**, on `POST /v1/apps` or `PATCH /v1/apps/{appId}`. The whole request is refused, so the app is neither created nor changed.

There is one entry per offending attachment, in request order, each carrying `no active secret with this name in this environment` and a pointer at `/secrets/<i>/secretName`. Create the secret in that environment first, or [copy one in](https://runware.ai/docs/serverless/secrets).

**The single-attach route responds differently.** `POST /v1/apps/{appId}/secrets` returns a [`404`](#not-found) for the same condition, because that handler reports a missing secret instead of a validation failure.

### Secret not attachable

**A `registry` secret cannot be attached to an app.** A registry login is read when an image is pulled, which happens before a worker exists, so it has no unseal path into a worker's environment. Nothing attaches it: it is stored for a build to read.

The entry points at `/secretName` on the single-attach route and at `/secrets/<i>/secretName` on create and update.

**It outranks a missing secret.** A request that lists both a registry secret and one that does not exist is answered with this type alone.

## Too many requests

`429` responds to the reads that count against your organization's allowance: logs, metrics and an app's request errors. It includes a **`Retry-After` that says how long to wait**, and a client that ignores it keeps being refused.

Reading an app, deploying and listing run outside that allowance. **One other condition returns `429`**, and it is the one below.

### Environment paused

The app's [environment](https://runware.ai/docs/serverless/environments) has spent its monthly budget and is set to pause there, so **its apps are stopped and no task starts**. The answer leaves out `Retry-After`, because **the pause ends on a budget or on a month instead of on a timer**: raise the budget past the spend, or wait for the UTC month to turn, then resume the app.

A request that would add capacity to a paused environment gets the same type with [`409`](#environment-cap-reached), the status for a state that refuses the change.

## Internal server error

`500` means the platform could not complete the request and no narrower answer fits.

One case is deliberate: **a usage summary refuses to report a total it cannot price in full**. A worker whose recorded life cannot be priced fails the whole request, because a total that silently omits usage is a wrong number the caller cannot see is wrong. There are no partial totals.

## Not implemented

`501` responds to a write to an [OIDC connector](https://runware.ai/docs/serverless/oidc-connectors) where the platform has no OIDC issuer. **Creating, updating and attaching one return it before they read or write anything**, so nothing partial happens.

Listing, reading, deleting and detaching keep working, which means a connector that is already there can always be inspected and removed.

## Bad gateway

`502` means a service this route depends on was unreachable or refused the request. **It is retryable, and it says nothing about your app or your account.**

Invoking an app is the case to handle with care. A `502` from a task route leaves the request's fate unknown, because **it may already have been accepted**. Retry it with the same `taskId`: an id the platform has already claimed returns the task it identifies instead of running the work twice. Reading a task or listing tasks can simply be retried.

## Service unavailable

`503` is **retryable**. It covers an active app the platform has observed to have no workload able to serve, and an organization whose Serverless tenancy is still being provisioned.

**No task is created**, so a retry is not a duplicate and cannot be charged twice. That is the difference from a [`502`](#bad-gateway) on a task route, where the work may already have been accepted.

It also responds to a create, source update, deploy, resume or scaling change when your credit balance could not be read at that moment. **That is not a refusal on credit**, and the same request can be sent again.

**Reading a task returns it too**, while the task or its output is briefly unavailable, for example while the task service is being updated. Nothing about the task changed, so the read can be repeated.

**Two types share the status.** `capacity-unavailable` is the platform being short of GPUs, and it includes a `Retry-After`. Everything else keeps `service-unavailable` and sends none, because **a workload that was removed does not come back by waiting**. A workload that failed to start usually needs the app corrected or redeployed, so read `health.reason` first.

**The detail can name your own failure.** Both types read `app has no workload able to serve this invocation`, and when the current spell recorded the last line your application printed before its container exited, that sentence follows it. A capacity shortfall has no line from an earlier spell, and a failed start looks back two minutes further. Switch on `type` and read `detail` for the diagnosis, the same line [monitoring](https://runware.ai/docs/serverless/monitoring) puts on the app's health.

> [!WARNING]
> `503` and `403` both mean "not available to you right now", but only one of them clears on its own. A tenancy still provisioning is a `503` and is retryable. A tenancy that was **revoked or never existed is a [`403`](#forbidden)** and retrying will not help.

### Capacity unavailable

The platform **has no GPUs to place your app's workers**. The request is refused before a task is minted, so retrying it is safe and it succeeds as sent once a worker can be placed.

```json
{
  "type": "https://docs.runware.ai/serverless/errors#capacity-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "app has no workload able to serve this invocation",
  "requestId": "6f1c..."
}
```

**Wait the `Retry-After`,** which is 30 seconds. Retrying sooner returns the same verdict, which has yet to be recalculated.

Only an **active** app is refused on this. An app still `initializing` that already has a version to route to accepts invocations while it reports itself unavailable, the ordinary case during a first deploy, and a draining app skips the gate entirely. See [Monitoring](https://runware.ai/docs/serverless/monitoring) for the health verdict this reads.

> [!NOTE]
> **A worker the platform never placed is not charged for**, because a pod with no node has no GPU. That is not the same as saying an unavailable app is free: a worker that *was* placed and cannot serve still has its GPU, and a container that crash-loops or is still loading is charged for, while one still pulling its image is not. An app reporting itself unavailable may still be accruing.

## Gateway timeout

`504` means the platform waited as long as it will wait and gave up.

The one you are most likely to meet is **`invoke-sync` reaching the platform deadline**. The task keeps running, and you go on reading it by its `taskId`. Raising an app's `requestTimeoutSecs` bounds the worker, not this deadline, so invoke a long job asynchronously. See [Invoking an app](https://runware.ai/docs/serverless/invoking).

## Failures inside your own code

The errors above are the platform refusing a request. When your handler itself raises, the request was accepted and **the failure is on the task instead**.

The task ends in `failed` and has the reason in `error`. **That string is not part of the contract**: it has no stable code and no retry signal, so read it, log it, show it to a human, but do not parse it to classify a failure.

```json
{
  "id": "6b0c...",
  "appId": "image-tools",
  "status": "failed",
  "endpointPath": "generate",
  "createdAt": "...",
  "output": null,
  "error": "..."
}
```

`error` is **a plain string with no code and no structured cause**. Read the status to detect the failure and surface the string to whoever has to debug it.