Handle API errors and retries with RunBridge AI - RunBridge AI

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:

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:

{
  "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:

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

Last modified on September 23, 2026