Errors

Introduction

Every error the Serverless API returns is an RFC 9457 problem document, served as application/problem+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 answers with has a row here, and a status that two conditions share has a row each, because the extension members are what tell those apart.

Bad request

400 means the request could not be parsed at all, most often a malformed JSON body. It carries no errors array, because nothing got far enough to be validated field by field.

A well-formed request that breaks a rule is a 422 instead. The split is worth keeping straight: 400 is "I could not read this", 422 is "I read it and it is wrong".

A log tail whose query the platform will not run also answers 400, and that one is final: the query has to change before the call can work, so a client that retries it loops on the same refusal.

Unauthorized

401 means the request carried no API key, or one the platform rejects. The key identifies your organization, so the fix is the Authorization header.

A key that is valid but belongs to an organization without Serverless access is a 403, not a 401.

Payment required

402 always means money rather than capacity, and it always carries 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.

{
  "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": "..."
}

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, 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 app is fine and the path is wrong.

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.

{
  "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 carries 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 at all is 404 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 for the flow they belong to.

An environment 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 answers 429 instead, since nothing about the app's own state is wrong.

Request entity too large

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

The limit is 10 MiB on invoke-sync and invoke-async, whose body carries 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 rather than 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) nor a schema failure (422).

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 at all 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, which tells you nothing about your body. A parameter that cannot be read comes next, so ?limit=nope sent as text/plain is a 400 rather than 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 rather than parsing detail.

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

{
  "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 at all. A code app's endpoint schemas are closed, so an unrecognized field is an error rather than something quietly dropped.

A container app declares its own schemas, and an endpoint that declares no input is a passthrough: it takes whatever JSON you send and never returns this error. See 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 names the parameter in detail and has no pointer, because a query string is not a JSON document.

Too many requests

429 answers the reads that draw on your organization's allowance: logs, metrics and an app's request errors. It carries 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 answers 429, and it is the one below.

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 answers a write to an OIDC connector where the platform has no OIDC issuer. Creating, updating and attaching one answer 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 names rather than running the work twice. Reading a task or listing tasks can simply be retried.

Service unavailable

503 is the only error worth retrying blindly. 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.

It also answers 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 answers 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 carries a Retry-After. Everything else keeps service-unavailable and sends none, because a workload that was removed does not come back by waiting.

{
  "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..."
}

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.

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 reaches failed and carries the reason in error. That string is not part of the contract: it carries 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.

{
  "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.