Errors

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

Overview

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://my.runware.ai/signup",
    "parameter": "apiKey",
    "taskType": "authentication"
  }
]
}

Each object in the errors array represents a single failed operation. When sending multiple tasks in one request errors are scoped to the specific task that failed, while other tasks in the same request 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

When using the HTTP REST API, the response also includes a standard HTTP status code alongside the errors array. These codes indicate 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 do not have HTTP status codes. For WebSocket integrations, use the code field in the error object to determine the error category.

Handling errors

For programmatic retry decisions, use HTTP status codes when on REST, or the error code field when on WebSocket. For debugging, always log the full message and taskUUID. The task UUID is the fastest way to get help from our support team.

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.