Error Codes and Error Handling

Every endpoint signals an error with a non-2xx status code plus a JSON error body. Use the HTTP status to decide between "fix the request" and "retry", then branch precisely on the machine code in the body.

Error Body Structure

Error details always live in the top-level error object:

{
  "error": {
    "message": "Human-readable error description",
    "type": "bad_request",
    "code": "optional_machine_code",
    "param": "image"
  }
}

Differences between endpoint families:

• Chat endpoints (/v1/chat/completions, /v1/responses): gateway-side errors are identified by error.code and usually carry no type; rate-limit errors also include retry_after_seconds.
• /v1/messages uses the Anthropic format: {"type": "error", "error": {"type": "invalid_request_error", "message": "..."}}, where error.type is an Anthropic value such as invalid_request_error / authentication_error / permission_error / rate_limit_error / api_error. There is no gateway machine code in this protocol, so handle errors by HTTP status (for example, insufficient balance is also 429).
• Image, speech, OCR, and vision segmentation use error.type primarily; some errors also carry code.

Recommended parsing:

def error_code(body: dict) -> str | None:
    err = body.get("error")
    if isinstance(err, dict):
        return err.get("code") or err.get("type")
    return err if isinstance(err, str) else None

Quick Reference by Status

Insufficient Balance and Pricing Errors

Insufficient balance returns 429, not 402. Distinguish it from ordinary rate limiting by the machine code:

{
  "error": {
    "code": "BILLING_BLOCKED",
    "message": "账户余额不足，请及时充值后重试",
    "type": "rate_limit_exceeded"
  }
}

• Prepaid accounts are blocked from new requests once the balance (including vouchers) is ≤ 0; service resumes automatically once a top-up lands.
• Reaching an organization or key daily / monthly budget, or a key's total spending cap, also returns BILLING_BLOCKED.
• On chat endpoints the message for this error may just say "too many requests" — branch on code.

402 pricing not configured means the model has no valid price for your organization yet, so the gateway rejects the request instead of serving it at zero cost. Contact support; retrying does not help.

{
  "error": {
    "code": "MISSING_MULTI_CURRENCY_PRICE",
    "message": "模型计价信息未确认,请联系客服处理",
    "type": "billing_error"
  }
}

Common Image Errors

{
  "error": {
    "message": "参考图片数量超出上限（最多 16 张）",
    "type": "bad_request",
    "param": "image"
  }
}

Retry Recommendations

• 400 / 401 / 402 / 403 / 451: request-side problems; retrying is pointless — fix and resend.
• 429: check code first — BILLING_BLOCKED needs a top-up; otherwise read the retry-after header and back off before retrying (use exponential backoff when it is absent). Never retry in a tight loop.
• 502 / 503 / 504: retry a limited number of times (≤ 3 recommended, exponential backoff), waiting for retry-after when present.
• When reporting an issue, keep the request ID from the response (such as the x-gateway-request-id header, if present) and the time it happened so support can locate it.