诺玛AI 诺玛AI
Đăng nhập Bảng điều khiển
Tài liệu/Xử lý lỗi

Xử lý lỗi

Hướng dẫn này giới thiệu định dạng phản hồi lỗi của 诺玛AI, các tình huống lỗi thường gặp cũng như các chiến lược xử lý được khuyến nghị.

Định dạng phản hồi lỗi#

Tất cả các phản hồi lỗi đều tuân theo định dạng JSON thống nhất:

Mã
{
  "error": {
    "code": "invalid_api_key",
    "message": "API Key được cung cấp không hợp lệ, vui lòng kiểm tra rồi thử lại.",
    "type": "authentication_error"
  }
}

Mã trạng thái HTTP#

Mã trạng thái

Loại

Mô tả

Có nên thử lại

`400`

`invalid_request_error`

Lỗi tham số yêu cầu

❌ Sửa tham số rồi thử lại

`401`

`authentication_error`

API Key không hợp lệ hoặc thiếu

❌ Kiểm tra API Key

`403`

`permission_error`

Không đủ quyền

❌ Kiểm tra quyền tài khoản

`404`

`not_found_error`

Mô hình hoặc tài nguyên không tồn tại

❌ Kiểm tra ID mô hình

`429`

`rate_limit_error`

Kích hoạt giới hạn tốc độ

✅ Chờ rồi thử lại

`500`

`internal_error`

Lỗi nội bộ máy chủ

✅ Thử lại sau

`502`

`upstream_error`

Lỗi nhà cung cấp mô hình thượng nguồn

✅ Đổi mô hình hoặc thử lại

`503`

`service_unavailable`

Dịch vụ tạm thời không khả dụng

✅ Thử lại sau

Lỗi thường gặp và giải pháp#

401 — API Key không hợp lệ

Mã
{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

Giải pháp:

  • Kiểm tra API Key đã được sao chép chính xác chưa (bao gồm tiền tố `sk-`)
  • Xác nhận Key chưa hết hạn hoặc bị vô hiệu hóa
  • Kiểm tra biến môi trường đã được tải đúng chưa

429 — Giới hạn tốc độ

Giải pháp:

  • Kiểm tra `x-ratelimit-reset-requests` trong Header phản hồi
  • Triển khai thử lại theo cơ chế lùi theo cấp số nhân
  • Nếu cần hạn mức cao hơn, liên hệ bộ phận hỗ trợ để yêu cầu điều chỉnh

502 — Lỗi thượng nguồn

Giải pháp:

  • Sử dụng cơ chế dự phòng để tự động chuyển sang mô hình thay thế
  • Thử lại sau
  • Kiểm tra trang trạng thái của nhà cung cấp mô hình

Chiến lược thử lại#

Khuyến nghị sử dụng chiến lược **lùi theo cấp số nhân (Exponential Backoff)**:

Mã
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<APINOMA_API_KEY của bạn>"
)

def chat_with_retry(max_retries=5, **kwargs):
    """Hàm bao bọc thử lại với cơ chế lùi theo cấp số nhân"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)

        except RateLimitError:
            # 429: Chờ rồi thử lại
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Bị giới hạn tốc độ, chờ {wait:.1f}s rồi thử lại...")
            time.sleep(wait)

        except APIConnectionError:
            # Lỗi mạng: chờ một lát rồi thử lại
            wait = 2 ** attempt
            print(f"Lỗi kết nối, chờ {wait}s rồi thử lại...")
            time.sleep(wait)

        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: Lỗi máy chủ, thử lại
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: Lỗi phía client, không thử lại
                raise

    raise Exception(f"Vẫn thất bại sau {max_retries} lần thử lại")

# Sử dụng
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Xin chào"}]
)

Cài đặt thời gian chờ#

Khuyến nghị cài đặt thời gian chờ hợp lý cho các lệnh gọi API:

Mã
# Python OpenAI SDK
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<APINOMA_API_KEY của bạn>",
    timeout=60.0,  # Thời gian chờ 60 giây
    max_retries=3  # Thử lại tích hợp sẵn trong SDK
)

Đối với các yêu cầu dạng luồng, nên sử dụng thời gian chờ dài hơn (120-300 giây), vì mô hình có thể cần nhiều thời gian hơn để tạo ra nội dung hoàn chỉnh.

Thực hành tốt nhất#

  • Phân biệt lỗi có thể thử lại và không thể thử lại — 4xx thường cần sửa đổi yêu cầu, 5xx có thể thử lại
  • Sử dụng cơ chế lùi theo cấp số nhân — tránh thử lại liên tục khi bị giới hạn tốc độ
  • Đặt số lần thử lại tối đa — ngăn việc thử lại vô hạn
  • Ghi lại nhật ký lỗi — thuận tiện cho việc khắc phục sự cố
  • Cấu hình cơ chế dự phòng — sử dụng tham số `provider.fallback` của 诺玛AI để tự động chuyển đổi mô hình
  • Giám sát tỷ lệ lỗi — theo dõi xu hướng lỗi trên bảng điều khiển

Cập nhật lần cuối vào 23 tháng 6, 2026