GuidesOneMux

Cách chẩn đoán an toàn lỗi xác thực, giới hạn tốc độ, timeout và phản hồi sai định dạng của OpenAI API

Hướng dẫn thực tế, chú trọng quyền riêng tư, giúp chẩn đoán lỗi xác thực, giới hạn tốc độ, timeout và phản hồi sai định dạng của OpenAI API mà không để lộ thông tin đăng nhập hay dữ liệu người dùng.

AI

Tóm tắt · TL;DR

Cách an toàn nhất để khắc phục sự cố OpenAI API là phân loại lỗi trước khi thử lại. Lỗi xác thực thường cần sửa key, tổ chức, project hoặc cấu hình IP; lỗi giới hạn tốc độ và quota cần điều chỉnh tốc độ gửi yêu cầu hoặc thay đổi cài đặt quản trị; timeout có thể chỉ là tạm thời; còn phản hồi sai định dạng nên được tách riêng thành lỗi truyền tải, proxy hoặc phân tích cú pháp. Hãy ghi lại metadata chẩn đoán, không ghi thông tin đăng nhập hoặc nội dung thô của người dùng.

Điểm chính

  • Không thử lại lỗi xác thực 401 hoặc lỗi thanh toán và quota như thể đó là lỗi mạng tạm thời.
  • Với lỗi giới hạn tốc độ 429 và phản hồi quá tải 503, hãy tuân theo Retry-After nếu có và áp dụng exponential backoff có giới hạn.
  • Không để API key xuất hiện trong mã nguồn, log, thông báo ngoại lệ hoặc ứng dụng phía client.
  • Xem phản hồi không phải JSON hoặc lỗi phân tích JSON là một vấn đề riêng về truyền tải hoặc proxy; chỉ thu thập thông tin chẩn đoán đã được ẩn dữ liệu và giới hạn kích thước.
  • Khi báo cáo sự cố kéo dài, hãy cung cấp model, mã lỗi, dấu thời gian, múi giờ và thông tin yêu cầu đã được làm sạch.
Mục lục (7)

Sẽ dễ khắc phục lỗi OpenAI API hơn nếu bạn phân loại riêng lỗi cấu hình, lỗi năng lực xử lý, lỗi mạng và lỗi phân tích cú pháp phản hồi. Câu hỏi chẩn đoán đầu tiên nên là: thử lại có khả năng làm thay đổi kết quả không?

Thử lại thường không giúp cải thiện lỗi 401. Lỗi 429 do gửi yêu cầu quá nhanh có thể được khắc phục bằng cách giãn nhịp gửi, trong khi lỗi 429 do hết credit hoặc chạm giới hạn chi tiêu cần thay đổi tài khoản hoặc project. Timeout có thể chỉ là sự cố tạm thời, nhưng timeout lặp lại có thể cho thấy vấn đề về mạng, proxy hoặc kích thước yêu cầu.

Các quy trình dưới đây sử dụng JavaScript và những khái niệm của thư viện OpenAI chính thức được trình bày trong hướng dẫn mã lỗi OpenAI. Đây là mẫu minh họa, không phải một tích hợp production đã được kiểm thử.

Trước khi gỡ lỗi: bảo vệ thông tin đăng nhập và dữ liệu người dùng

Hãy áp dụng các biện pháp sau trước khi tái hiện lỗi:

  • Lưu API key trong trình quản lý bí mật phía server hoặc biến môi trường. Không bao giờ đưa key vào mã trình duyệt, ứng dụng di động, hệ thống quản lý mã nguồn hoặc phiếu yêu cầu hỗ trợ.
  • Ghi lại dấu thời gian của yêu cầu, nhóm endpoint, mã model, HTTP status và mã lỗi có cấu trúc nếu có.
  • Không ghi log header Authorization, toàn bộ nội dung yêu cầu, nội dung phản hồi thô hoặc prompt có dữ liệu cá nhân.
  • Nếu cần prompt để chẩn đoán, hãy ghi một mẫu đã ẩn dữ liệu hoặc mã định danh yêu cầu nội bộ ổn định thay vì văn bản gốc.
  • Giới hạn độ dài dữ liệu chẩn đoán. Proxy có thể trả về một trang lỗi HTML lớn, còn lỗi từ upstream có thể chứa dữ liệu bạn không định lưu giữ.

Một nguyên tắc vận hành hữu ích là log phải trả lời được lỗi xảy ra ở đâu và lỗi gì, nhưng không ghi lại người dùng đã nói gì hoặc cách xác thực.

Ưu tiên chẩn đoán lỗi xác thực 401

Các trường hợp 401 được tài liệu nêu gồm xác thực không hợp lệ, API key sai, thiếu tư cách thành viên tổ chức và địa chỉ IP không được cấp quyền. Lỗi 403 có thể cho biết quốc gia, khu vực hoặc vùng lãnh thổ không được hỗ trợ.

Hãy kiểm tra lần lượt các mục sau:

  1. Xác nhận server đang đọc đúng secret và secret không bị cắt cụt, hết hạn, thu hồi hoặc thay thế.
  2. Xác nhận yêu cầu được gửi đến đúng API endpoint và project.
  3. Nếu cấu hình của bạn sử dụng mã định danh tổ chức hoặc danh sách IP được phép, hãy đối chiếu cả hai với cấu hình project.
  4. Kiểm tra xem yêu cầu có xuất phát từ một IP egress khác trong môi trường phát triển, container hoặc môi trường lưu trữ hay không.
  5. Xóa mọi giá trị thông tin xác thực khỏi đầu ra gỡ lỗi trước khi chia sẻ log.

Không tự động thử lại lỗi 401 hoặc 403. Thử lại cùng một thông tin xác thực không hợp lệ có thể tạo thêm nhiễu và làm phức tạp quá trình phân tích sự cố. Hãy sửa cấu hình rồi gửi yêu cầu mới.

Phân biệt lỗi giới hạn tốc độ 429 với lỗi quota và thanh toán

Không phải lỗi 429 nào cũng có nghĩa là “đợi một lát rồi thử lại”. Hướng dẫn của OpenAI phân biệt một số trường hợp sau:

Nhóm lỗiHướng xử lý khả dĩTự động thử lại?
Đã chạm giới hạn tốc độGiãn nhịp gửi yêu cầu và tuân theo Retry-After nếu cóCó, nhưng cần giới hạn
slow_downGiảm tốc độ gửi yêu cầu rồi tăng dầnCó, thận trọng
Đã hết số dư creditNạp thêm creditKhông
Đã chạm giới hạn chi tiêu của tổ chức hoặc projectThay đổi giới hạn tương ứngKhông
Đã chạm giới hạn sử dụng của tổ chứcYêu cầu tăng giới hạn đã được phê duyệt hoặc liên hệ bộ phận hỗ trợKhông

Vòng lặp thử lại nên kiểm tra HTTP status và mã lỗi cụ thể thay vì xử lý mọi lỗi 429 như nhau. Hãy đặt số lần thử tối đa, dùng exponential backoff và jitter để nhiều worker không thử lại cùng lúc. Nếu có Retry-After, hãy ưu tiên thời gian chờ đó, nhưng vẫn áp dụng mức chờ tối đa của riêng bạn.

Cũng cần tính đến phản hồi 503. Tài liệu nguồn xác định lỗi model quá tải bằng server_is_overloaded và khuyến nghị tuân theo Retry-After nếu có trước khi thử lại. Trong thư viện Python, lỗi quá tải có thể được biểu diễn bằng InternalServerError, còn lỗi 429 dùng RateLimitError; trình xử lý không nên mặc định rằng lỗi quá tải luôn xuất hiện dưới dạng 429.

Kiểm tra timeout và lỗi kết nối

Thư viện Python chính thức ghi nhận APITimeoutError cho các yêu cầu bị timeout và APIConnectionError cho sự cố kết nối. Một số điểm cần kiểm tra thường gặp:

  • Timeout trước khi nhận được phản hồi: kiểm tra cài đặt timeout của client, tuyến mạng, proxy, tường lửa và kích thước yêu cầu.
  • Lỗi kết nối: kiểm tra DNS, chứng chỉ TLS, quy tắc tường lửa outbound và cấu hình proxy.
  • Lỗi phía server lặp lại: kiểm tra trang trạng thái dịch vụ và lưu lại dấu thời gian đã được làm sạch để cung cấp cho bộ phận hỗ trợ.

Timeout không chứng minh rằng server chưa xử lý yêu cầu. Với các thao tác có rủi ro phát sinh công việc trùng lặp, hãy thiết kế ứng dụng sao cho có thể đối soát an toàn khi thử lại—chẳng hạn bằng cách gắn thao tác với bản ghi yêu cầu của riêng bạn. Không khắc phục timeout bằng cách tăng thời gian chờ vô hạn hoặc thử lại không giới hạn.

Xử lý phản hồi sai định dạng mà không làm lộ nội dung

“Phản hồi sai định dạng” có thể mô tả nhiều vấn đề khác nhau: yêu cầu không hợp lệ dẫn đến BadRequestError, phản hồi không khớp schema mong đợi, hoặc proxy trả về HTML hay dữ liệu bị cắt cụt thay vì JSON. Hướng dẫn OpenAI mô tả BadRequestError là yêu cầu sai định dạng hoặc chưa đầy đủ, đồng thời khuyến nghị kiểm tra tham số bắt buộc, encoding, định dạng và kích thước.

Với HTTP client thô hoặc middleware, hãy kiểm tra riêng từng mục sau:

  1. Kiểm tra HTTP status và Content-Type trước khi phân tích cú pháp.
  2. Thực hiện phân tích JSON bên trong một khối được bảo vệ lỗi.
  3. Xác thực các trường bắt buộc tồn tại trước khi sử dụng.
  4. Chỉ ghi lại status, content type, độ dài phản hồi và một đoạn trích đã ẩn dữ liệu, giới hạn kích thước nếu chính sách cho phép.
  5. Không đưa API key, prompt đầy đủ hoặc toàn bộ phản hồi vào thông báo lỗi phân tích cú pháp.

Một wrapper minh họa có thể như sau:

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

Ví dụ này cố ý không đưa nội dung phản hồi vào lỗi được ném ra. Trong môi trường production, hãy bổ sung xác thực schema phù hợp với endpoint và chỉ lưu payload thô theo quy trình chẩn đoán có kiểm soát, đã được rà soát về quyền riêng tư.

Mẫu trình xử lý lỗi chú trọng quyền riêng tư

Ví dụ chính thức của JavaScript phân biệt lỗi kết nối, lỗi giới hạn tốc độ và các lỗi API tổng quát. Bạn có thể mở rộng cách tiếp cận đó bằng cách phân loại lỗi mà không in ra thông tin bí mật hoặc dữ liệu đầu vào của người dùng:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

Hãy kiểm tra tên class và cách hoạt động của endpoint theo phiên bản SDK bạn triển khai. Không nên mặc định rằng mọi endpoint tương thích với provider đều hỗ trợ mọi tham số SDK hoặc trường phản hồi.

Khi nào cần chuyển cấp xử lý

Với sự cố kéo dài, hướng dẫn OpenAI khuyến nghị cung cấp model, thông báo lỗi và mã lỗi, dữ liệu yêu cầu và header, dấu thời gian, múi giờ cùng các thông tin liên quan khác. Trước tiên, hãy làm sạch gói thông tin đó: thay thông tin xác thực, xóa cookie, ẩn dữ liệu cá nhân và tóm tắt nội dung yêu cầu nếu có thể. Không bao giờ đăng thông tin nhạy cảm lên diễn đàn công khai.

Nguyên tắc thực tế rất đơn giản: sửa lỗi xác thực và quota; giảm tốc độ gửi khi gặp lỗi giới hạn tốc độ và quá tải; kiểm tra các điểm kết nối mạng khi bị timeout; và tách riêng lỗi phân tích cú pháp mà không lưu giữ payload riêng tư.

FAQ

Có nên thử lại mọi phản hồi 429 của OpenAI không?

Không. Với phản hồi do tốc độ gửi yêu cầu hoặc slow-down, hãy thử lại thận trọng bằng backoff và tuân theo Retry-After nếu có. Không nên kỳ vọng thử lại sẽ khắc phục tình trạng hết credit, chạm giới hạn chi tiêu hoặc giới hạn sử dụng của tổ chức.

Vì sao lỗi quá tải của OpenAI có thể xuất hiện dưới dạng 503 thay vì 429?

Hướng dẫn lỗi OpenAI ghi nhận tình trạng model quá tải dưới dạng 503 với mã server_is_overloaded. Trình xử lý lỗi nên kiểm tra cả status lẫn mã lỗi, thay vì mặc định rằng lỗi quá tải luôn là phản hồi giới hạn tốc độ.

Nên ghi log thông tin gì khi gặp lỗi xác thực OpenAI?

Hãy ghi dấu thời gian, môi trường, nhóm endpoint, status và mã lỗi đã được làm sạch. Không ghi API key, header Authorization, toàn bộ nội dung yêu cầu hoặc prompt thô của người dùng.

Cách khắc phục phản hồi JSON không hợp lệ là gì?

Kiểm tra HTTP status và Content-Type trước khi phân tích cú pháp; chỉ thu thập thông tin chẩn đoán đã được giới hạn và ẩn dữ liệu nếu chính sách cho phép; đồng thời kiểm tra proxy hoặc middleware có thể đang trả về HTML, cắt cụt dữ liệu hoặc thay đổi phản hồi.

Bài viết liên quan