> ## 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 API errors and retries with RunBridge AI

> Handle RunBridge AI errors by separating request-shape problems, authentication failures, rate limits, and retryable platform failures.

Handle RunBridge AI errors by deciding whether the request should be fixed or retried. Retry `429`, timeout-class failures, and temporary server failures with backoff; do not retry malformed requests or authentication failures.

## Retry only retryable failures

| Status or signal | Retry? | Action |
| - | - | - |
| `400` | No | Fix the request body or parameters. |
| `401` | No | Fix the API key and `Authorization` header. |
| `403` | Usually no | Remove unsupported fields and verify model access. |
| `429` | Yes | Retry with exponential backoff and jitter. |
| `500` with `invalid_request` | No | Fix the request shape. |
| `500`, `503`, `504`, `524` | Yes | Retry with backoff and keep the request ID. |

## Add backoff

The following Python example retries only retryable failures:

```python theme={null}
import os
import random
import time
from openai import APIError, OpenAI, RateLimitError

client = OpenAI(
    api_key=os.environ["RUNBRIDGE_API_KEY"],
    base_url="https://api.runbridge.ai/v1",
)

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="your-model-id",
            messages=[{"role": "user", "content": "Say hello."}],
        )
        print(response.choices[0].message.content)
        break
    except RateLimitError:
        delay = min(30, 2**attempt) + random.random()
        time.sleep(delay)
    except APIError as error:
        status_code = getattr(error, "status_code", None)
        if status_code in {500, 503, 504, 524}:
            delay = min(30, 2**attempt) + random.random()
            time.sleep(delay)
            continue
        raise
else:
    raise RuntimeError("The request failed after retries.")
```

The successful response includes the model output:

```json theme={null}
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello."
      }
    }
  ],
  "usage": {
    "total_tokens": 9
  }
}
```

## Log useful context

The following JSON shape is safe to store after you remove user secrets and large files:

```json theme={null}
{
  "method": "POST",
  "path": "/v1/chat/completions",
  "model": "your-model-id",
  "status": 429,
  "request_id": "request_id_from_error_message",
  "retryable": true
}
```

## Common errors

| Error | Fix |
| - | - |
| Retrying `401` | Stop retries and rotate or reload the API key. |
| Retrying invalid JSON | Validate the request body before sending another request. |
| No request ID in logs | Capture the exact error body before your SDK wraps it. |
| Immediate retry after `429` | Add jitter and reduce concurrency. |

## Related links

* [Error Codes & Handling](/errors/error-codes-handling)
* [Rate limits and concurrency](/guides/rate-limits-and-concurrency)
* [Models page](/overview/models)
* [Model directory](https://runbridge.ai/models/)
* [Pricing](https://runbridge.ai/pricing/)
* [RunBridge AI quickstart](/overview/quick-start)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "TechArticle",
        "@id": "https://runbridge.mintlify.site/guides/error-codes-and-retry-strategy",
        "headline": "How do I handle error codes and retries with RunBridge AI?",
        "description": "Handle RunBridge AI errors by separating request-shape problems, authentication failures, rate limits, and retryable platform failures.",
        "url": "https://runbridge.mintlify.site/guides/error-codes-and-retry-strategy",
        "author": {
          "@type": "Organization",
          "name": "RunBridge AI"
        },
        "publisher": {
          "@type": "Organization",
          "name": "RunBridge AI",
          "url": "https://runbridge.ai"
        }
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "RunBridge AI Docs",
            "item": "https://runbridge.mintlify.site/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Guides",
            "item": "https://runbridge.mintlify.site/guides/use-runbridge-with-openai-sdk"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "How do I handle error codes and retries with RunBridge AI?",
            "item": "https://runbridge.mintlify.site/guides/error-codes-and-retry-strategy"
          }
        ]
      }
    ]
    }
    `}
</script>


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