> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runbridge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle error codes

> Use this guide to classify RunBridge AI error responses and apply retry or fix steps for common request failures.

Classify RunBridge AI errors as **request validation problems**, **authentication problems**, **path mistakes**, or **retryable service failures**. Use HTTP status, `error.code`, and `error.message` to decide whether to fix the request or retry it.

## Quick triage

| Status | What it usually means | Retry? | First action |
| - | - | - | - |
| `400` | Request validation failed before the request was processed normally. | No | Validate `model`, `messages`, JSON shape, and field types. |
| `401` | API key is missing, malformed, or invalid. | No | Check the authentication headers in the matching API reference. |
| `403` | Access was blocked or the current request was not allowed. | Usually no | Retry with a known-good request and remove model-specific fields first. |
| Path mistake | Wrong base URL or wrong endpoint path. On RunBridge AI this may appear as a `301` redirect or HTML. | No | Match the base URL and operation path to the API reference, and disable automatic redirects while debugging. |
| `429` | Rate limiting or temporary saturation. | Yes | Use exponential backoff with jitter. |
| `500` with `error.code: invalid_request` | A malformed request surfaced through a server-status response. | No | Fix the request body before retrying. |
| `500`, `503`, `504`, `524` | Service failure or timeout. | Yes | Retry with backoff and keep the request ID. |

For an image request that returned a task ID, [retrieve the existing task](/api/image/openai/image-generation-task) after a timeout. Repeating a creation request can generate another image and incur another charge. If you have no task ID, keep the request ID and timestamp for support before submitting it again.

## Error envelope

Many RunBridge AI failures use an error body like this:

```json theme={null}
{
	"error": {
		"message": "...",
		"type": "runbridge_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

Some responses leave `code` empty. When the status is `500`, treat `error.code` and `error.message` as the deciding signal.

## `400 Bad Request`

A `400` usually means the request body failed validation before the request could be processed normally.

Common causes:

* Missing required fields such as `model`
* Invalid JSON shape
* Sending a field with the wrong type
* Reusing model-specific parameters that the selected endpoint does not accept

Start from a minimal known-good request, then add optional fields back one by one. Compare the payload against the endpoint schema in the API reference.

Use a minimal request like this:

```json theme={null}
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
```

Replace `your-model-id` with any current model ID from the [RunBridge AI Models page](/overview/models).

Do not assume every malformed chat request returns `400`. Missing required chat fields such as `messages` can also surface as `500` with `error.code: invalid_request`.

## `500 Internal Server Error`

Most `500` responses indicate a service failure. For Chat Completions, some malformed requests can also surface as `500` while still carrying `error.code: invalid_request`.

One example is a request that omits `messages`:

```json theme={null}
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "runbridge_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

If a `500` response has `error.code: invalid_request`, treat it as a request problem:

1. Fix the request body.
2. Compare the payload against the endpoint schema.
3. Retry only after correcting the payload.

If a `500` response does not point to an invalid request, keep the `request id` and use backoff.

## `401 Invalid Token`

A token failure usually looks like this:

```json theme={null}
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "runbridge_api_error"
	}
}
```

What to check:

1. For OpenAI-compatible requests, use `Authorization: Bearer $RUNBRIDGE_API_KEY`. For Anthropic Messages or Gemini, follow the authentication headers in the matching API reference.
2. Make sure your app is not loading an old key from `.env`, shell history, or a deployed secret store.
3. If one key fails and another key works on the same request, treat this as a token issue, not an endpoint issue.

## `403 Forbidden`

`403` is most often one of these situations:

* The request is blocked by a platform-side rule such as WAF filtering
* The token or route is not allowed to use the requested model or request shape
* The chosen model rejects one of the advanced parameters you passed

What to do first:

1. Retry with a very simple text request against a known-good model.
2. Remove advanced and model-specific fields, then add them back gradually.
3. If the response includes a request id, keep it before contacting support.

## Wrong base URL or wrong path

On RunBridge AI, a path mistake may surface as:

* A redirect
* A non-JSON HTML response if your client follows redirects
* A parsing error inside your SDK
* A request that never reaches the API layer cleanly

Match your SDK's base URL to its request format:

| Request format | SDK base URL |
| - | - |
| OpenAI-compatible SDKs | `https://api.runbridge.ai/v1` |
| Anthropic Messages or Google Gemini | `https://api.runbridge.ai` |

Recommended checks:

1. Confirm the base URL matches the SDK configuration in the API reference.
2. Confirm the complete request URL matches the documented operation path.
3. Disable automatic redirect following while debugging path problems.

## `413 Request Entity Too Large`

If you see `413`, treat it as a **request size** problem first. Common suspects are:

* Large base64 payloads
* Oversized image, audio, or video inputs embedded in a multimodal LLM request
* Very large multipart or JSON bodies

What to do:

1. Reduce or compress attached content.
2. Split large jobs into smaller requests.
3. Do not assume plain text length is the only cause.

## `429 Too Many Requests`

Treat `429` as retryable:

1. Use exponential backoff with jitter.
2. Reduce burst concurrency.
3. Keep request logging on so you can see which route and model are saturating first.

For a reusable retry pattern, see the backoff example on [Chat Completions](/api/text/chat).

## `503`, `504`, and `524`

These statuses are **server-side or timeout-class failures**.

Practical guidance:

* `503`: service temporarily unavailable
* `504` and `524`: a request timed out

What to do:

1. Retry with backoff.
2. Keep the `request id`, endpoint, model, and timestamp.
3. If the same failure repeats across multiple retries, contact support with that context.

## Before you contact support

Capture these details first:

* HTTP method
* Endpoint path
* Model ID
* Sanitized request body JSON
* Query parameters if the failing request used them
* Exact response body if your client captured it
* Full HTTP status
* The exact `error.message`
* Any `request id`
* Approximate timestamp
* Whether the same request works with another model or another token

If the failing route accepts **file uploads**, such as a GPT Image editing request, include the submitted fields and file metadata:

* Field names and text values you sent alongside the file
* File name, file type, and approximate file size
* Whether the file was uploaded directly, referenced by URL, or embedded as base64

<Warning>
  Include the sanitized request payload with your support request. For JSON requests, provide the **request body JSON**. For file uploads, provide the field list and file metadata.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.