GuidesOneMux

Lỗi OpenAI API trong môi trường production: Chẩn đoán, thử lại và khôi phục an toàn

Quy trình thực tế để chẩn đoán lỗi xác thực, giới hạn tốc độ, timeout, máy chủ và phản hồi sai định dạng của OpenAI trong môi trường production, đồng thời quyết định khi nào nên thử lại, khắc phục hoặc chuyển sang quy trình khôi phục.

AI

Tóm tắt · TL;DR

Xử lý lỗi trong môi trường production cần bắt đầu bằng việc phân loại lỗi, không phải thử lại mọi yêu cầu. Hướng dẫn này phân biệt lỗi cấu hình và hạn mức với tình trạng bị giới hạn tốc độ tạm thời, timeout, lỗi máy chủ và phản hồi không hợp lệ, sau đó đưa ra mẫu thử lại JavaScript có giới hạn cùng danh sách kiểm tra khôi phục.

Điểm chính

  • Không thử lại lỗi xác thực, quyền truy cập, yêu cầu sai định dạng hoặc hết tín dụng nếu chưa khắc phục nguyên nhân.
  • Khi bị giới hạn tốc độ hoặc quá tải, hãy tuân theo `Retry-After` nếu có và giới hạn số lần thử lại bằng exponential backoff cùng jitter.
  • Timeout không chứng minh thao tác đã thất bại; tránh lặp lại một cách mù quáng các tác vụ không idempotent.
  • Xác thực phản hồi thành công trước khi cập nhật trạng thái quy trình ở các bước tiếp theo, đồng thời lưu đủ ngữ cảnh để khôi phục an toàn.
Mục lục (6)

Nguyên tắc trong production: phân loại trước khi thử lại

Khi lệnh gọi OpenAI API thất bại, câu hỏi hữu ích không chỉ đơn giản là “Có nên thử lại không?” mà là “Bằng chứng nào cho thấy lỗi này chỉ là tạm thời, và yêu cầu trùng lặp sẽ gây ra điều gì?” Quy trình production cần phân loại lỗi, áp dụng hành động có giới hạn và giữ nguyên trạng thái của tác vụ nếu không thể tiếp tục một cách an toàn.

OpenAI mô tả các nguyên nhân riêng biệt gây ra lỗi xác thực, giới hạn tốc độ, hết tín dụng hoặc vượt hạn mức chi tiêu, lỗi máy chủ và mô hình quá tải. Chỉ riêng mã trạng thái không phải lúc nào cũng đủ: hãy kiểm tra cả mã lỗi và thông báo lỗi. Xem hướng dẫn mã lỗi của OpenAI để biết các nguyên nhân và cách khắc phục được tài liệu hóa.

Phân loại theo loại lỗi

Triệu chứngHành động có thể cần thực hiệnThử lại?
Lỗi xác thực 401Kiểm tra API key có chính xác và còn hiệu lực không, đồng thời xác nhận đang dùng đúng tổ chức dự kiến. Kiểm tra danh sách IP được phép nếu đã cấu hình.Không, cho đến khi thông tin xác thực hoặc quyền truy cập được khắc phục.
Yêu cầu không hợp lệ 400Kiểm tra thông báo và tham số yêu cầu, bao gồm dữ liệu đầu vào bắt buộc, mã hóa, định dạng và kích thước.Không, cho đến khi yêu cầu được sửa.
429 do giới hạn tốc độ hoặc thông báo “slow down”Giảm số yêu cầu đồng thời hoặc tốc độ gửi yêu cầu. Tuân theo Retry-After nếu có, sau đó tăng lưu lượng dần dần.Có, trong phạm vi chính sách thử lại có giới hạn.
429 do tín dụng, chi tiêu hoặc giới hạn sử dụngKiểm tra error.code; bổ sung tín dụng hoặc xử lý giới hạn tương ứng.Không. Gửi lại cùng yêu cầu sẽ không khôi phục quyền truy cập.
Lỗi máy chủ 500 hoặc quá tải 503Chờ trong thời gian ngắn, tuân theo Retry-After nếu có và thử lại trong giới hạn cho phép.Thường là có, kèm biện pháp bảo vệ.
Timeout phía máy khách hoặc lỗi kết nốiKiểm tra mạng, proxy, TLS và tường lửa; xác định liệu yêu cầu có thể đã được xử lý hay chưa.Có thể; trước tiên cần tính đến các tác động trùng lặp.
Trạng thái thành công nhưng phản hồi không dùng đượcXác thực cấu trúc phản hồi và các trường bắt buộc trước khi chuyển quy trình sang bước tiếp theo.Không tự động thử lại. Hãy xử lý riêng như lỗi chất lượng dữ liệu hoặc giao thức.

Hướng dẫn của OpenAI lưu ý rằng RateLimitError trong Python tương ứng với 429, còn InternalServerError tương ứng với 503; vì vậy, tình trạng quá tải có thể xuất hiện với mã trạng thái khác với mã mà trình xử lý trước đó dự kiến. Trong mọi client, hãy dựa vào cả trạng thái lẫn chi tiết lỗi, thay vì mặc định mọi trường hợp quá tải đều là 429.

Mẫu thử lại JavaScript có giới hạn

Điều kiện tiên quyết: phiên bản OpenAI JavaScript SDK hiện hành, API key đã được cấu hình và quy trình có thể xác định an toàn liệu có nên gửi lại yêu cầu hay không. Ví dụ minh họa này chỉ thử lại một số lỗi tạm thời nhất định. Nó không chứng minh rằng yêu cầu bị timeout chưa được xử lý.

import OpenAI from "openai";

const client = new OpenAI();

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryAfterMs(error) {
  const value = error.headers?.get?.("retry-after");
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

  const dateMs = Date.parse(value);
  return Number.isNaN(dateMs) ? null : Math.max(0, dateMs - Date.now());
}

function isRetryable(error) {
  const code = error.code;
  if ([
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
  ].includes(code)) return false;

  return error instanceof OpenAI.RateLimitError ||
    (error instanceof OpenAI.APIError &&
      [500, 503].includes(error.status));
}

async function createResponseWithRetry(input, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await client.responses.create({
        model: "YOUR_MODEL",
        input,
      });
    } catch (error) {
      if (!isRetryable(error) || attempt >= maxRetries) throw error;

      const exponentialMs = Math.min(10_000, 500 * 2 ** attempt);
      const jitterMs = Math.floor(Math.random() * 250);
      const delayMs = retryAfterMs(error) ?? exponentialMs + jitterMs;
      await sleep(delayMs);
    }
  }
}

YOUR_MODEL là biến giữ chỗ, không phải đề xuất về model. Ví dụ này minh họa cách kiểm soát việc thử lại, không khẳng định hành vi đã được kiểm thử trên mọi phiên bản SDK hoặc endpoint. Hãy xác nhận SDK có cung cấp header phản hồi như minh họa trong phiên bản bạn đã cài đặt hay không; nếu không, hãy dùng cơ chế được hỗ trợ để đọc chúng. Ngoài số lần thử lại, hãy đặt thời hạn ở cấp quy trình để tác vụ bị đình trệ không phải chờ vô thời hạn.

Đừng thêm lỗi xác thực, yêu cầu sai định dạng, quyền truy cập hoặc hạn mức vào isRetryable. Trước tiên, hãy sửa cấu hình hoặc quyền truy cập. Cũng nên cân nhắc ngân sách thử lại cho mỗi tác vụ và giới hạn số tác vụ đồng thời ở cấp hàng đợi: nếu mọi worker đều gửi lại ngay lập tức, việc thử lại có thể làm trầm trọng thêm đột biến lưu lượng.

Timeout và phản hồi sai định dạng cần có quy tắc khôi phục

Timeout có nghĩa là client không nhận được phản hồi kịp thời; điều đó không xác định được liệu máy chủ đã hoàn tất thao tác hay chưa. Trước khi thử lại, hãy quyết định xem có thể chấp nhận việc xử lý trùng lặp hay không. Với các tác vụ có hành động tiếp theo quan trọng, hãy lưu mã định danh và trạng thái xử lý của tác vụ, đồng thời thiết kế các thao tác ghi tiếp theo theo hướng idempotent nếu có thể. Nếu chưa rõ kết quả, hãy đánh dấu tác vụ để đối soát thay vì mù quáng khởi chạy lại.

Hãy xem bước xác thực phản hồi là một phần riêng trong quy trình. Kiểm tra đối tượng phản hồi có tồn tại không, có nội dung mong đợi không, và mọi đầu ra có cấu trúc có phân tích cú pháp được cũng như đáp ứng schema của ứng dụng hay không. Không được ghi nhận phản hồi không vượt qua bước xác thực là kết quả thành công. Ghi lại thông tin chẩn đoán an toàn, sau đó chuyển phản hồi sang quy trình sửa lỗi hoặc rà soát có giới hạn; đừng mặc định rằng gửi lại yêu cầu y hệt sẽ khắc phục nội dung sai định dạng.

Danh sách kiểm tra vận hành

  1. Ghi nhật ký thời điểm và múi giờ, endpoint, model, trạng thái HTTP, loại và mã lỗi, cùng mã tương quan yêu cầu an toàn.
  2. Không bao giờ ghi API key hoặc dữ liệu đầu vào nhạy cảm vào nhật ký. Chỉ lưu chi tiết yêu cầu cần thiết để tái hiện lỗi một cách an toàn.
  3. Chỉ thử lại lỗi tạm thời, với số lần thử tối đa, thời gian chờ, jitter và thời hạn tổng thể.
  4. Tuân theo Retry-After nếu được cung cấp; tiếp tục giảm tốc độ nếu tình trạng giới hạn vẫn tiếp diễn.
  5. Phân biệt trường hợp đã thử hết số lần cho phép với lỗi vĩnh viễn để người vận hành có thể kiểm tra và chạy lại các tác vụ đủ điều kiện.
  6. Với lỗi kéo dài, thu thập model, thông báo và mã lỗi, dữ liệu yêu cầu và header đã loại bỏ bí mật, thời điểm và múi giờ cùng ngữ cảnh liên quan khác. OpenAI khuyến nghị cung cấp các chi tiết này cho bộ phận hỗ trợ.

Kết luận

Quy trình OpenAI API đáng tin cậy cần phân biệt áp lực dịch vụ tạm thời với lỗi đòi hỏi thay đổi cấu hình hoặc hạn mức. Hãy thận trọng khi thử lại lỗi giới hạn tốc độ và lỗi dịch vụ; khắc phục lỗi xác thực và yêu cầu; đồng thời coi timeout và đầu ra không hợp lệ là các trạng thái cần khôi phục rõ ràng. Việc phân loại này giúp vòng lặp thử lại không biến một lệnh gọi thất bại thành sự cố production nghiêm trọng hơn.

FAQ

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

Không. Với phản hồi do giới hạn tốc độ, hãy thử lại theo nhịp độ hợp lý, giới hạn số lần và tuân theo `Retry-After` nếu có. Nếu 429 do hết tín dụng hoặc vượt hạn mức chi tiêu hay sử dụng, cần khắc phục giới hạn đó; gửi lại lệnh gọi sẽ không khôi phục quyền truy cập. Hãy kiểm tra mã lỗi.

Quy trình nên xử lý timeout OpenAI API như thế nào?

Hãy coi kết quả là chưa rõ: client có thể đã timeout dù quá trình xử lý hoàn tất. Trước khi thử lại, hãy cân nhắc tác động trùng lặp, dùng các thao tác tiếp theo idempotent nếu có thể và chuyển những tác vụ chưa rõ kết quả sang bước đối soát.

Tôi nên làm gì khi API trả về phản hồi sai định dạng?

Xác thực cấu trúc phản hồi và các trường bắt buộc trước khi lưu hoặc thực hiện hành động. Không đưa tác vụ vào trạng thái thành công; hãy ghi lại thông tin chẩn đoán an toàn và dùng quy trình sửa lỗi hoặc rà soát có kiểm soát thay vì tự động gửi lại yêu cầu y hệt.

503 có nghĩa giống 429 không?

Không. Hướng dẫn OpenAI được cung cấp mô tả phản hồi 429 do giới hạn tốc độ và phản hồi 503 do mô hình quá tải là hai trường hợp riêng biệt. Client nên kiểm tra trạng thái và chi tiết lỗi, đồng thời xử lý cả hai khi phù hợp, thay vì cho rằng tình trạng quá tải luôn xuất hiện dưới dạng 429.

Bài viết liên quan