Errors

ModelBridge returns standard HTTP status codes and JSON error responses. This page covers the errors you may encounter and how to handle them.

Error format

All errors follow this JSON structure:

Error format

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "error_type",
    "code": "error_code"
  }
}

Status codes

Status	Meaning	Common cause
`400`	Bad Request	Malformed JSON, missing required fields, invalid model name
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Key lacks access to the requested resource
`404`	Not Found	Invalid endpoint path
`429`	Too Many Requests	Spending limit reached or rate limited
`500`	Internal Server Error	Upstream provider error or ModelBridge issue
`502`	Bad Gateway	Upstream provider is unreachable
`504`	Gateway Timeout	Upstream provider took too long to respond

Common errors

Invalid API key

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Fix: Check that your API key is correct, starts with mb_, and hasn't been revoked. Regenerate it from the dashboard if needed.

Model not found

{
  "error": {
    "message": "Model 'gpt-4' not found",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Fix: Use the exact model ID from the Models page. Model names are case-sensitive. Use /v1/models to list available models.

Spending limit reached

{
  "error": {
    "message": "Spending limit reached for this API key",
    "type": "rate_limit_error",
    "code": "spending_limit_exceeded"
  }
}

Fix: Increase the spending limit on your API key in the dashboard, top up your balance, or use a different key.

Insufficient balance

{
  "error": {
    "message": "Insufficient balance",
    "type": "rate_limit_error",
    "code": "insufficient_balance"
  }
}

Fix: Add funds to your account via the billing page.

Upstream timeout

{
  "error": {
    "message": "Upstream request timed out",
    "type": "server_error",
    "code": "timeout"
  }
}

Fix: Retry the request. Larger models (like Claude Opus) may take longer. If timeouts persist, try a faster model or reduce your prompt size.

Handling errors in code

from openai import OpenAI, APIError, AuthenticationError, RateLimitError

client = OpenAI(
    base_url="https://api.modelbridge.dev/v1",
    api_key="mb_live_your_key_here",
)

try:
    response = client.chat.completions.create(
        model="claude-sonnet-4-6",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    print("Invalid API key. Check your credentials.")
except RateLimitError:
    print("Spending limit reached. Top up your balance.")
except APIError as e:
    print(f"API error: {e.message}")

Retry strategy

For 429 and 5xx errors, implement exponential backoff:

Wait 1 second, retry
Wait 2 seconds, retry
Wait 4 seconds, retry
Give up after 3-5 attempts

The OpenAI SDKs include built-in retry logic with backoff. Configure retries via:

Retry configuration

client = OpenAI(
    base_url="https://api.modelbridge.dev/v1",
    api_key="mb_live_your_key_here",
    max_retries=3,
)