Error Codes

Error Codes

Error response format

Error envelopes vary by endpoint. Use HTTP status and error.type when present; error.code may be a string or numeric HTTP status, and can be absent. Use error.message for display only.

{
  "error": {
    "message": "Insufficient credits. Please top up to continue.",
    "type": "invalid_request_error",
    "code": "insufficient_credits"
  }
}

HTTP status and error.code

Error envelopes vary by endpoint. Use HTTP status and error.type when present; error.code may be a string or numeric HTTP status, and can be absent. Use error.message for display only.

Machine-readable billing codes

A 402 response can represent different controls. These stable codes let clients show the correct next action.

Detailed error codes

When an API request fails, error.code tells you the specific reason. Two errors can both use HTTP 400 but require different fixes: unknown_model means the model name is wrong, while image_too_large means the image must be reduced. Use the table below to find the cause and next action.

Content Moderation

All requests are automatically reviewed before being sent to the model. Requests that violate our usage policy are rejected before dispatch and return a 403 error.

Categories that get blocked

Moderation is based on our Acceptable Use Policy and primarily blocks the following categories of content:

• Sexual exploitation content
• Violent threats
• Operational guidance for illegal acts
• Biohazard-related content

403 response format

A request blocked by moderation returns an error in this shape:

{
  "error": {
    "message": "Your prompt was blocked by content moderation.",
    "type": "invalid_request_error",
    "code": "content_filter"
  }
}

Blocked requests are not billed — you are not charged for a rejected request.

Appealing a false positive

If you believe a request was blocked incorrectly, contact support with the request time and (if convenient) the request id, and we'll review it.

Privacy

Requests are automatically reviewed for content safety; the text and images of your latest input may be sent to a third-party content-safety scoring service.

For requests judged violating, suspected, near the threshold or randomly sampled, we may keep the full text or the leading portion for compliance evidence, dispute handling and auditing, with no fixed deletion period promised.

Other ordinary successful requests do not have their prompts or responses retained; requests made with ZDR keys are not subject to the first two points.

Rate limits, budgets, and emergency brakes

These controls can reject an otherwise valid request. They are separate from provider failures and require different recovery actions.

Error envelopes vary by endpoint. Use HTTP status and error.type when present; error.code may be a string or numeric HTTP status, and can be absent. Use error.message for display only.

Video and media resource state

Video validation commonly returns numeric code 400. A missing job returns 404, a retired model returns 410, unfinished video content returns 409, and an invalid video byte range returns 416. Poll until completion or correct the Range header before retrying.

Retry policy

Retry only failures that may recover without changing the request. When Retry-After is present, wait that long; otherwise use exponential backoff with jitter. Limit attempts and avoid layering manual retries on top of SDK automatic retries.

Handling Errors

import random
import time
from openai import OpenAI, APIStatusError

client = OpenAI(
    base_url="https://api.bazaarlink.ai/v1",
    api_key="sk-bl-YOUR_API_KEY",
    max_retries=0,  # Avoid double retries; this example handles them.
)

RETRYABLE = {429, 502, 503, 504}

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="openai/gpt-4o",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        break
    except APIStatusError as error:
        if error.status_code not in RETRYABLE or attempt == 4:
            raise
        retry_after = error.response.headers.get("Retry-After")
        delay = (
            float(retry_after)
            if retry_after
            else min(8, 0.5 * (2 ** attempt)) + random.uniform(0, 0.25)
        )
        time.sleep(delay)

Streaming Error Formats

Errors that occur before any tokens are streamed return a standard HTTP error response with a JSON body.

After a stream has started, the HTTP response is already 200. Parse every SSE data frame and treat a top-level error or choices[0].finish_reason === "error" as a failed, incomplete response.

If a stream fails after it starts, BazaarLink may emit a final SSE event with a top-level error object followed by data: [DONE]. Treat the response as incomplete; do not use partial output as a completed result.

data: {"error":{"message":"The request could not be completed.","type":"upstream_error","code":502}}

data: [DONE]

// Branch on error.code; error.type can vary by failure path.