---
title: Errors | Runware Docs
url: https://runware.ai/docs/models-api/errors
description: Understanding error responses from the Runware API and how to handle them in your integration.
relatedDocuments:
  - https://runware.ai/docs/models-api/rate-limits
  - https://runware.ai/docs/models-api/task-polling
---
## 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**:

```json
{
"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. |
| `retryAfter` | integer | The number of seconds to wait before retrying, on errors that name a wait. |
| `documentation` | string | A link to relevant documentation for the parameter. |

> [!NOTE]
> 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** - The request was not accepted, because the model's queue is over capacity or your organization passed its rate limit. Retry after the wait in the `Retry-After` header. See [Rate Limits](https://runware.ai/docs/models-api/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`).

When an error carries `retryAfter`, **wait that many seconds** before sending the task again and skip your own backoff delay for that attempt. This is the case for `serviceOverloaded`, which the API returns when a model's queue is over capacity. Over HTTP the wait also arrives in the `Retry-After` header.

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](https://runware.ai/docs/models-api/rate-limits) for detailed retry implementation patterns.