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

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

> [!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

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