Errors

Understanding error responses from the Runware API and how to handle them in your integration.

Introduction

When a request fails, the Runware API returns a JSON response containing an errors array. This format is consistent across both HTTP REST and WebSocket connections.

Error Response

{
"errors": [
  {
    "code": "invalidApiKey",
    "message": "Invalid API key. Get one at https://runware.ai/signup",
    "parameter": "apiKey",
    "taskType": "authentication"
  }
]
}

Each object in the errors array represents a single failed operation. When you send multiple tasks in one request, errors are scoped to the task that failed and the rest may still succeed.

Error fields

Field	Type	Description
`code`	string	A short identifier for the error (e.g., `invalidApiKey`, `timeoutProvider`).
`message`	string	A human-readable explanation with details about what went wrong.
`parameter`	string	The request parameter related to the error, if applicable.
`taskType`	string	The task type of the request that failed.
`taskUUID`	string	The unique identifier of the request that failed, useful for debugging and support.
`documentation`	string	A link to relevant documentation for the parameter.

We are actively standardizing our error codes and response formats. During this transition, you may encounter error codes or message formats that vary between models and providers. We recommend logging the full message and taskUUID fields to debug issues effectively.

HTTP status codes

Over the HTTP REST API, the response also carries a standard HTTP status code alongside the errors array. These codes name the general category of the failure:

Code	Description
`400`	Bad Request - The request was unacceptable, often due to missing a required parameter.
`401`	Unauthorized - No valid API key provided.
`402`	Payment Required - Your account balance is insufficient.
`403`	Forbidden - The API key doesn't have permissions to perform the request.
`404`	Not Found - The requested resource doesn't exist.
`429`	Too Many Requests - Too many requests hit the API too quickly. See Rate Limits.
`500`	Server Error - Something went wrong on Runware's end.
`503`	Service Unavailable - The service is temporarily unavailable (e.g., maintenance or capacity).

WebSocket connections have no HTTP status codes. Read the code field in the error object instead to tell the categories apart.

Handling errors

For retry decisions, read the HTTP status code on REST and the error code on WebSocket. For debugging, log the full message and taskUUID: the task UUID is the fastest way to get help from support.

Retries

For transient errors, it is often safe to retry the request with exponential backoff. These include:

HTTP 429 (Too Many Requests) and 5xx (Server Error) status codes.
Error codes indicating capacity or provider issues (e.g., timeoutProvider, providerRateLimitExceeded).

For client errors such as invalid parameters or authentication failures, you should not retry without modifying the request, as it will fail again. See Rate Limits for detailed retry implementation patterns.