Lỗi API AI thường gặp: 400, 401, 403, 429, 500, 529 của OpenAI, Claude, Gemini và cách sửa

Đọc lỗi API thế nào?

Mỗi lỗi có ba phần nên đọc: mã HTTP (400, 429…), kiểu lỗi trong thân JSON (ví dụ rate_limit_error, invalid_api_key) và mã yêu cầu để gửi hỗ trợ (x-request-id của OpenAI, request-id của Anthropic). Cùng một mã HTTP có thể có nhiều nguyên nhân, nên đọc kiểu lỗi và thông điệp trước khi thử lại hay đổi thanh toán.

Nếu bạn gọi qua một gateway (đặt base_url hay ANTHROPIC_BASE_URL khác địa chỉ của hãng), mã và thông điệp lỗi do gateway trả, không phải của hãng; tài liệu Claude Code ghi rõ điều này với lỗi 401 và 5xx.

Bảng tra nhanh: lỗi nào thử lại, lỗi nào phải sửa

Theo hướng dẫn của cả ba hãng:

• Nên thử lại với thời gian chờ tăng dần: 408, 429 do gửi quá nhanh, 500, 502, 503, 504 và 529.
• Không thử lại, phải sửa trước: 400 (request sai), 401 (sai key), 403 (không có quyền, sai vùng), 404 (sai model, sai địa chỉ), 413 (request quá lớn), và mọi lỗi liên quan tiền: hết credit trả trước, chạm trần chi tiêu, chạm hạn mức tháng.
• Request thất bại vẫn bị tính vào giới hạn theo phút, nên thử lại dồn dập chỉ làm lỗi kéo dài.

Lỗi 400: request sai định dạng hoặc vượt ngữ cảnh

400 nghĩa là chính request có vấn đề; gửi lại y nguyên sẽ lỗi y nguyên:

• OpenAI và Anthropic: kiểu lỗi invalid_request_error, thường do sai tên tham số, sai kiểu dữ liệu, sai tên model hoặc JSON hỏng.
• Vượt cửa sổ ngữ cảnh: Claude báo “prompt is too long” khi riêng phần input đã vượt cửa sổ ngữ cảnh; Responses API của OpenAI trả 400 khi input vượt ngữ cảnh mà truncation để mặc định. Cách sửa: bớt lịch sử, tóm tắt, hoặc dùng RAG để chỉ gửi đoạn cần.
• Anthropic: phiên bản API 2026-10-21 (ra ngày 21/10/2026) bỏ temperature, top_p, top_k; gửi các tham số này là lỗi 400. Các SDK bản mới gửi phiên bản này mặc định. Chạm hạn mức chi tiêu tự đặt cho tổ chức cũng trả 400 với câu “You have reached your specified API usage limits”.
• Gemini: sai API key ở generateContent trả 400 INVALID_ARGUMENT (lý do API_KEY_INVALID), không phải 401; còn 400 FAILED_PRECONDITION nghĩa là gói miễn phí không có ở nước bạn đang gọi, cần bật thanh toán trong Google AI Studio.

Lỗi 401: sai hoặc hết hạn API key

Thử gọi bằng key giả ngày 25/10/2026: OpenAI trả “Incorrect API key provided” với mã invalid_api_key, Anthropic trả authentication_error “invalid x-api-key”. Nguyên nhân hay gặp:

• Chép thiếu, thừa khoảng trắng hoặc dấu xuống dòng; key đã bị xoá, thu hồi, hoặc hết hạn (Anthropic cho đặt hạn dùng cho key từ tháng 7/2026).
• Key thuộc tổ chức hay project khác với cái bạn đang gọi; OpenAI còn trả 401 khi IP không nằm trong danh sách IP được phép của project.
• Biến môi trường đè nhau: SDK Gemini ưu tiên GOOGLE_API_KEY hơn GEMINI_API_KEY; Claude Code dùng ANTHROPIC_API_KEY nếu có, kể cả key cũ nạp từ file .env.
• Cách lấy và lưu key đúng có ở bài cách lấy API key OpenAI, Claude, Gemini.

Lỗi 403: không có quyền hoặc sai vùng

403 nghĩa là key hợp lệ nhưng không được phép làm việc đó:

• OpenAI: “Country, region, or territory not supported” khi gọi từ nơi không được hỗ trợ. Anthropic: permission_error khi key không có quyền với tài nguyên. Gemini: PERMISSION_DENIED khi key bị báo lộ, project bị hạn chế hoặc tài khoản thanh toán còn nợ.
• Việt Nam có trong danh sách vùng được hỗ trợ của cả OpenAI, Anthropic và Gemini. Gặp lỗi vùng khi đang ở Việt Nam thường là do máy chủ, proxy hay hàm serverless của bạn chạy ở nước khác; kiểm vùng triển khai trước.
• Đừng dùng VPN để lách vùng: các hãng có thể khoá tài khoản. Chi tiết với Claude có ở bài Claude có dùng được ở Việt Nam không.
• Gemini báo key bị lộ thì phải tạo key mới; tạo key mới trong cùng project không gỡ được hạn chế ở cấp project.

Lỗi 429: gửi quá nhanh hay hết hạn mức?

429 có hai nhóm nguyên nhân, cách xử lý ngược nhau:

• Gửi quá nhanh: vượt số request hay token mỗi phút. Giới hạn được áp theo từng khoảng ngắn, nên 60 request mỗi phút có thể bị áp thành 1 request mỗi giây và một đợt dồn ngắn vẫn dính lỗi. OpenAI còn trả slow_down khi lưu lượng tăng quá nhanh; Anthropic có giới hạn tăng tốc tương tự. Cách sửa: chờ theo header retry-after nếu có, thử lại với thời gian chờ tăng dần, giảm số request song song, đặt max_tokens sát độ dài cần vì OpenAI tính cả con số này vào giới hạn token.
• Hết tiền hay hạn mức: OpenAI có các mã credit_balance_exhausted, organization_spend_limit_exceeded, project_spend_limit_exceeded, organization_usage_limit_exceeded (kiểu lỗi có thể vẫn ghi insufficient_quota); Anthropic trả 429 không kèm retry-after khi tổ chức chạm trần chi tiêu tháng của bậc tài khoản, mở lại lúc 00:00 UTC ngày 1 tháng sau. Thử lại không giúp gì; phải nạp thêm, nâng trần hoặc chờ kỳ mới.
• Gemini: 429 RESOURCE_EXHAUSTED khi vượt giới hạn theo phút, theo ngày hoặc giới hạn chi tiêu trong 10 phút; giới hạn tính theo project chứ không theo từng key, giới hạn theo ngày đặt lại lúc nửa đêm giờ Thái Bình Dương.
• Header cho biết còn bao nhiêu: x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens của OpenAI; nhóm anthropic-ratelimit-* của Anthropic.
• Hạn mức của gói Claude Pro, Max khi dùng Claude Code là chuyện khác với giới hạn API; xem bài Claude Code hết hạn mức.

Lỗi 500, 503, 529: nhà cung cấp lỗi hoặc quá tải

Nhóm này là lỗi phía hãng, không phải do request hay tài khoản của bạn:

• OpenAI: 500 là lỗi máy chủ; 503 server_is_overloaded là model tạm thiếu tài nguyên, có thể kèm Retry-After.
• Anthropic: 500 api_error; 504 timeout_error khi request chạy quá lâu, nên dùng streaming cho request dài; 529 overloaded_error khi hệ thống quá tải chung. Theo tài liệu Claude Code, 529 không phải hạn mức của bạn và không trừ quota; Claude Code tự thử lại tới 10 lần, vẫn lỗi thì đổi model bằng /model.
• Gemini: 500 INTERNAL (có khi do ngữ cảnh quá dài), 503 UNAVAILABLE khi quá tải, 504 DEADLINE_EXCEEDED khi không xử lý kịp.
• Xem trang trạng thái trước khi sửa code: status.openai.com, status.claude.com, aistudio.google.com/status.
• Khi streaming, lỗi có thể đến sau khi đã nhận mã 200, dưới dạng sự kiện lỗi trong luồng; đừng tự động gửi lại request khi đã nhận một phần câu trả lời.

Hết credit trả trước

Tài khoản API mới của OpenAI, Gemini và Console của Anthropic đều trả trước. Hết số dư thì OpenAI trả lỗi credit_balance_exhausted; Anthropic báo “Your credit balance is too low to access the Anthropic API” (kiểu lỗi billing_error hoặc invalid_request_error); Gemini ngừng mọi API key gắn với tài khoản thanh toán đó cho tới khi nạp thêm. Số dư cập nhật có độ trễ vài phút, nên có thể dùng vượt một chút trước khi bị chặn. Thẻ bị từ chối khi nạp thì xem bài thẻ bị từ chối khi nạp API.

Viết vòng thử lại đúng cách

SDK chính thức đã tự thử lại: SDK Python của OpenAI và Anthropic mặc định 2 lần, có tôn trọng retry-after; SDK Python của Gemini tới 4 lần. Nếu tự viết vòng thử lại thì tắt thử lại của SDK, để không nhân số request lên nhiều lần. Nguyên tắc: chờ theo retry-after nếu có, không thì chờ tăng gấp đôi (1, 2, 4, 8 giây…) kèm một khoảng ngẫu nhiên, giới hạn số lần và tổng thời gian, và không thử lại lỗi liên quan tiền. Ví dụ với SDK Python của OpenAI:

import random
import time

from openai import APIStatusError, OpenAI

client = OpenAI(max_retries=0)  # tự thử lại bên dưới, tắt thử lại của SDK
RETRYABLE = {408, 429, 500, 502, 503, 504, 529}
BILLING = {
    "credit_balance_exhausted",
    "insufficient_quota",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}


def wait_seconds(error, attempt):
    header = error.response.headers.get("retry-after")
    try:
        return float(header)
    except (TypeError, ValueError):
        return min(60, 2**attempt) + random.uniform(0, 1)


def create_with_retry(max_attempts=6, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except APIStatusError as error:
            last_try = attempt == max_attempts - 1
            if error.status_code not in RETRYABLE or error.code in BILLING or last_try:
                raise
            time.sleep(wait_seconds(error, attempt))

Khi gọi model qua STEYG Code

Qua STEYG Code, ứng dụng và coding agent gọi một base URL theo chuẩn OpenAI hoặc Anthropic cho Claude, GPT, DeepSeek, GLM và Qwen; mã và thông điệp lỗi khi đó do gateway trả, mô tả ở tài liệu API. Ngân sách trả trước bằng VND, hết thì dừng, không bao giờ bị tính quá số tiền đã trả. Cách cấu hình từng công cụ có ở bài OpenAI-compatible API là gì.

Câu hỏi thường gặp