API ErrorsTroubleshootingClaude APICodex APIDDS Hub

Mã lỗi API Claude, Codex, GLM và Kimi: Hướng dẫn khắc phục đầy đủ

Khi tích hợp Claude, Codex, GLM, Kimi hoặc các mô hình ngôn ngữ lớn khác vào một ứng dụng, lỗi API là điều không thể tránh khỏi. Một yêu cầu hoạt động hoàn hảo ngày hôm qua có thể đột nhiên trả về 400 Bad Request, 429 Too Many Requests hoặc 502 Bad Gateway, và thông báo lỗi mà client hiển thị không phải lúc nào cũng giải thích được điều gì thực sự đã sai.

Điều này càng trở nên phức tạp hơn khi các lập trình viên sử dụng một API gateway hoặc dịch vụ chuyển tiếp (relay). Một yêu cầu không nhất thiết phải đi trực tiếp từ ứng dụng đến nhà cung cấp mô hình. Thay vào đó, nó có thể đi qua nhiều lớp chịu trách nhiệm xác thực, định tuyến mô hình, lựa chọn tài khoản, chuyển đổi giao thức, giới hạn tần suất và chuyển đổi dự phòng (failover) phía thượng nguồn.

Do đó, hiểu được chuỗi yêu cầu này quan trọng hơn việc ghi nhớ từng mã trạng thái HTTP riêng lẻ.

Hướng dẫn này giải thích những lỗi Claude API, lỗi Codex API, lỗi GLM API và lỗi Kimi API phổ biến nhất, bao gồm 400, 401, 403, 404, 408, 429, 500, 502, 503 và 504. Nó cũng giải thích tại sao lỗi 502 không nhất thiết có nghĩa là bản thân API gateway bị hỏng, làm thế nào để xác định lỗi thượng nguồn thực sự, và các lập trình viên có thể làm gì để giải quyết những vấn đề này.

Cách một yêu cầu API AI thực sự hoạt động

Trước khi khắc phục sự cố lỗi API, việc hiểu toàn bộ đường đi của yêu cầu sẽ rất hữu ích.

Một yêu cầu API trực tiếp điển hình trông như thế này:

text

Your Application
      ↓
AI Provider API
      ↓
Claude / Codex / GLM / Kimi

Khi sử dụng một API gateway hoặc nền tảng chuyển tiếp, kiến trúc trở nên phức tạp hơn:

text

Your Application
      ↓
API Gateway
      ↓
Authentication
      ↓
Model / Group Routing
      ↓
Channel Selection
      ↓
Upstream Account
      ↓
AI Provider
      ↓
Claude / Codex / GLM / Kimi

Mỗi lớp có thể tạo ra một loại lỗi khác nhau.

Ví dụ, một API key không hợp lệ có thể tạo ra lỗi 401 trước khi yêu cầu chạm tới nhà cung cấp mô hình. Một yêu cầu bị định dạng sai có thể tạo ra lỗi 400 trong quá trình chuyển đổi giao thức. Một giới hạn hạn ngạch từ phía nhà cung cấp có thể dẫn đến lỗi 429, trong khi một yêu cầu thượng nguồn thất bại có thể được hiển thị cho client dưới dạng 502.

Đây là lý do tại sao chỉ riêng mã trạng thái HTTP thường là không đủ.

Tham khảo nhanh: Các mã lỗi API AI phổ biến

Code	Meaning	Common Cause	First Thing to Check
400	Bad Request	Tham số không hợp lệ hoặc không được hỗ trợ	Nội dung yêu cầu và mô hình
401	Unauthorized	API key không hợp lệ	Ủy quyền (Authorization)
403	Forbidden	Hạn chế quyền hoặc truy cập	Quyền của tài khoản và mô hình
404	Not Found	Endpoint hoặc tài nguyên không khả dụng	URL và mô hình
408	Request Timeout	Yêu cầu mất quá nhiều thời gian	Mạng và thời gian chờ
429	Too Many Requests	Giới hạn tần suất hoặc hạn ngạch	RPM, TPM, hạn ngạch
500	Internal Server Error	Lỗi phía máy chủ	Nhật ký gateway/nhà cung cấp
502	Bad Gateway	Yêu cầu thượng nguồn thất bại	Lỗi thượng nguồn
503	Service Unavailable	Dịch vụ tạm thời không khả dụng	Trạng thái nhà cung cấp/kênh
504	Gateway Timeout	Thượng nguồn hết thời gian chờ	Thời gian chờ và độ trễ nhà cung cấp

Sự phân biệt quan trọng nhất là giữa lỗi yêu cầu phía client và lỗi hạ tầng thượng nguồn.

400 Bad Request: Kiểm tra yêu cầu trước khi đổ lỗi cho mô hình

Lỗi 400 Bad Request thường có nghĩa là máy chủ đã nhận được yêu cầu nhưng không thể xử lý nó vì có điều gì đó trong yêu cầu không hợp lệ hoặc không được hỗ trợ.

Đối với các API Claude, Codex, GLM và Kimi, những nguyên nhân phổ biến bao gồm tên mô hình không hợp lệ, tham số không được hỗ trợ, các lời gọi công cụ (tool call) được định dạng không đúng, lịch sử tin nhắn bị định dạng sai, hoặc không tương thích giao thức.

Điều này đặc biệt phổ biến khi các lập trình viên sử dụng các API tương thích với OpenAI, vì các nhà cung cấp khác nhau không nhất thiết hỗ trợ chính xác cùng một schema yêu cầu.

Ví dụ, một client có thể gửi:

json

{
  "model": "gpt-5.5",
  "metadata": {},
  "input": [...]
}

API công khai có thể hỗ trợ metadata, trong khi một endpoint thượng nguồn nội bộ được gateway sử dụng lại có thể từ chối nó. Một sự cố gần đây của Sub2API đã ghi lại chính xác tình huống này: metadata được chuyển tiếp đến một endpoint Codex thượng nguồn không chấp nhận trường này, dẫn đến lỗi 400 phía thượng nguồn, mà sau đó Sub2API hiển thị dưới dạng 502.

Một sự cố khác của Sub2API đã ghi lại việc một tham số user không được hỗ trợ được chuyển tiếp qua /v1/responses, một lần nữa gây ra lỗi 400 phía thượng nguồn.

Giải pháp thường là kiểm tra yêu cầu đối chiếu với schema API thượng nguồn thực tế thay vì giả định rằng mọi endpoint tương thích OpenAI đều hỗ trợ mọi tham số của OpenAI.

Khi gỡ lỗi một lỗi 400, hãy bắt đầu với tên mô hình, endpoint, các tham số yêu cầu, định nghĩa công cụ, các trường thinking hoặc reasoning, lịch sử tin nhắn và định dạng giao thức.

Lỗi 400 của Claude API: Vấn đề với Thinking và Signature

Các quy trình lập trình dựa trên Claude có thể tạo ra một loại lỗi 400 khác liên quan đến các khối thinking và signature.

Một sự cố gần đây của Sub2API đã báo cáo:

text

API Error: 400

Invalid `signature` in `thinking` block

Cùng một yêu cầu sau đó có thể tạo ra một thông báo Upstream request failed chung chung cho client.

Loại lỗi này đặc biệt liên quan đến Claude Code và các ứng dụng kiểu agent, vì các cuộc hội thoại không còn là những chuỗi tin nhắn người dùng và văn bản trợ lý đơn giản nữa. Yêu cầu có thể chứa các khối thinking, các lời gọi công cụ, kết quả công cụ và nội dung có cấu trúc khác.

Nếu một proxy hoặc gateway sửa đổi, loại bỏ hoặc tái tạo không chính xác một phần trạng thái hội thoại đó, mô hình thượng nguồn có thể từ chối yêu cầu.

Vì lý do này, khi Claude Code đột nhiên bắt đầu trả về lỗi 400 trong các tác vụ nhiều lượt, các lập trình viên nên kiểm tra xem vấn đề có chỉ xảy ra với thinking, công cụ, hoặc các cuộc hội thoại kéo dài hay không thay vì ngay lập tức cho rằng API key đã hết hạn.

401 Unauthorized: Kiểm tra API Key của bạn

Lỗi 401 thường có nghĩa là máy chủ không thể xác thực yêu cầu.

Điều đầu tiên cần kiểm tra là header Authorization:

text

Authorization: Bearer YOUR_API_KEY

Nếu bạn đang sử dụng Claude, Codex, GLM hoặc Kimi thông qua một gateway, hãy đảm bảo rằng bạn đang sử dụng API key của gateway, chứ không phải thông tin đăng nhập của nhà cung cấp thượng nguồn.

Sự phân biệt này rất quan trọng vì yêu cầu có thể có hai lớp xác thực hoàn toàn khác nhau:

text

Client API Key
      ↓
Gateway
      ↓
Upstream Account

Một tài khoản thượng nguồn hợp lệ không nhất thiết có nghĩa là API key phía client hợp lệ.

Nếu mọi mô hình đều trả về 401, hãy kiểm tra cấu hình client trước. Nếu chỉ một nhóm hoặc mô hình trả về 401, hãy điều tra cấu hình kênh hoặc tài khoản thượng nguồn của gateway.

403 Forbidden: Xác thực hoạt động, nhưng quyền thì không

Lỗi 403 khác với lỗi 401.

Với 401, máy chủ không chấp nhận việc xác thực của bạn.

Với 403, yêu cầu có thể đã được xác thực, nhưng người dùng, API key, tài khoản, mô hình hoặc kênh không có quyền để thực hiện thao tác.

Ví dụ, một gateway có thể cho phép người dùng gọi Claude Sonnet nhưng không cho phép một mô hình cao cấp cụ thể. Một kênh cũng có thể được cấu hình cho một nhóm cụ thể trong khi một mô hình khác lại không khả dụng.

Nếu một lập trình viên báo cáo:

"API key của tôi hoạt động, nhưng mô hình cụ thể này trả về lỗi 403."

thì những điều đầu tiên cần kiểm tra là tính khả dụng của mô hình, cấu hình nhóm, quyền tài khoản và các hạn chế của nhà cung cấp.

Đừng ngay lập tức tạo một API key khác.

404 Not Found: Vấn đề với Endpoint hoặc Mô hình

Lỗi 404 thường có nghĩa là tài nguyên được yêu cầu không tồn tại.

Trong các ứng dụng AI, điều này có thể mang nhiều ý nghĩa.

Endpoint có thể bị sai:

text

/v1/chat/completions

so với:

text

/v1/responses

Mô hình có thể không tồn tại trong nhóm đã chọn, hoặc nhà cung cấp thượng nguồn có thể không cung cấp endpoint được yêu cầu.

Điều này đặc biệt quan trọng đối với các mô hình mới hơn vì tên mô hình và khả năng tương thích endpoint có thể thay đổi.

Khi khắc phục sự cố lỗi 404, hãy xác minh Base URL, endpoint, tên mô hình, nhà cung cấp và cấu hình kênh.

Một cách kiểm tra hữu ích là gọi endpoint được hỗ trợ đơn giản nhất với yêu cầu đơn giản nhất có thể trước khi thử nghiệm các tính năng nâng cao như công cụ, reasoning, tạo ảnh hoặc streaming.

429 Too Many Requests: Giới hạn tần suất hay hạn ngạch?

429 là một trong những lỗi phổ biến nhất mà các lập trình viên gặp phải khi làm việc với các API AI.

Cách hiểu hiển nhiên là:

Quá nhiều yêu cầu.

Nhưng trên thực tế, 429 có thể đại diện cho nhiều giới hạn khác nhau.

Nhà cung cấp có thể đang thực thi giới hạn số yêu cầu mỗi phút, số token mỗi phút, hạn ngạch cấp tài khoản, giới hạn đồng thời, hoặc các hạn chế công suất tạm thời.

Đây là lý do tại sao việc giảm tần suất yêu cầu không phải lúc nào cũng đủ.

Giả sử một coding agent tạo ra một lượng lớn ngữ cảnh và gửi nhiều yêu cầu cùng lúc. Ngay cả khi số lượng yêu cầu thấp, ứng dụng vẫn có thể chạm tới một giới hạn dựa trên token.

Do đó, quá trình khắc phục sự cố nên xem xét:

Possible Limitation	What to Check
RPM	Số yêu cầu mỗi phút
TPM	Số token mỗi phút
Concurrency	Số yêu cầu đồng thời
Account quota	Hạn ngạch còn lại của nhà cung cấp
Model capacity	Tính khả dụng hiện tại của nhà cung cấp
Gateway limits	Giới hạn tần suất cấp nền tảng

Đối với các ứng dụng có lưu lượng lớn, logic thử lại (retry) với backoff theo cấp số nhân cũng có thể hữu ích. Tuy nhiên, việc liên tục thử lại một yêu cầu ngay lập tức có thể làm tình hình tồi tệ hơn bằng cách tăng tải.

500 Internal Server Error: Điều gì đó đã thất bại trên máy chủ

Lỗi 500 thường có nghĩa là máy chủ đã gặp phải một lỗi nội bộ không mong muốn.

Khi sử dụng một API gateway, điều quan trọng là xác định xem lỗi 500 đến từ gateway hay từ nhà cung cấp thượng nguồn.

Nếu bản thân gateway tạo ra lỗi, quản trị viên nên kiểm tra nhật ký ứng dụng, kết nối cơ sở dữ liệu, Redis, cấu hình kênh, lựa chọn tài khoản và các thay đổi triển khai gần đây.

Nếu nhà cung cấp thượng nguồn trả về 500, gateway có thể chỉ đơn giản là chuyển tiếp hoặc bao bọc lỗi thượng nguồn đó.

Đối với khách hàng, thông tin hữu ích nhất do đó không chỉ là:

text

500 Internal Server Error

mà còn là request ID, mô hình, kênh và dấu thời gian liên quan.

502 Bad Gateway: Lỗi mà các lập trình viên hiểu sai nhiều nhất

502 đáng được chú ý đặc biệt vì nó cực kỳ phổ biến trong các kiến trúc API gateway.

Nhiều lập trình viên nhìn thấy:

text

502 Bad Gateway

và ngay lập tức kết luận:

"API gateway đã ngừng hoạt động."

Điều đó không nhất thiết đúng.

Một gateway có thể trả về 502 vì nó đã nhận yêu cầu thành công nhưng không thể lấy được phản hồi hợp lệ từ dịch vụ thượng nguồn.

Một chuỗi yêu cầu đơn giản hóa trông như thế này:

text

Client
  ↓
Gateway
  ↓
Upstream
  ↓
400
  ↓
Gateway
  ↓
502
  ↓
Client

Hành vi này đã được ghi nhận nhiều lần trong các sự cố của Sub2API.

Ví dụ, một sự cố gần đây cho thấy một lỗi 400 phía thượng nguồn do một tham số background không được hỗ trợ gây ra, trong khi client chỉ nhận được:

text

502 Upstream request failed

Nguyên nhân thực sự có thể thấy được trong nhật ký gateway dưới dạng một lỗi 400 Unsupported parameter: background phía thượng nguồn.

Một sự cố khác liên quan đến các yêu cầu OpenAI Responses API chứa các tin nhắn hệ thống ở một dạng không được hỗ trợ. Thượng nguồn đã từ chối yêu cầu, trong khi Sub2API trả về 502 Bad Gateway cho client.

Do đó, 502 nên được xem như một tín hiệu để kiểm tra lỗi thượng nguồn, chứ không phải là chẩn đoán cuối cùng.

Codex và Responses API: Tại sao 502 có thể trở nên phức tạp

Các quy trình kiểu Codex có thể khiến việc khắc phục sự cố gateway trở nên đặc biệt khó khăn vì Responses API hỗ trợ các tương tác có trạng thái (stateful) và nhiều lượt.

Ví dụ, một sự cố của Sub2API đã ghi lại tình huống trong đó cùng một phiên Codex logic được định tuyến giữa các tài khoản OpenAI thượng nguồn khác nhau. Ngữ cảnh được mã hóa do một tài khoản tạo ra không thể được xác minh bởi một tài khoản khác, khiến thượng nguồn trả về 400, trong khi gateway trả về 502.

Kiến trúc trông đại khái như sau:

text

Codex Session
     ↓
Gateway
     ↓
Account A
     ↓
Encrypted Context
     ↓
Retry
     ↓
Account B
     ↓
Cannot decrypt context
     ↓
Upstream 400
     ↓
Gateway 502

Điều này minh họa tại sao việc luân chuyển tài khoản ngẫu nhiên đơn giản không phải lúc nào cũng phù hợp với các API có trạng thái.

Đối với các ứng dụng sử dụng Codex, Responses API, ngữ cảnh được mã hóa, lời gọi công cụ hoặc các phiên nhiều lượt, gateway có thể cần tính liên kết phiên (session affinity) để các yêu cầu liên quan vẫn được gắn với một tài khoản thượng nguồn tương thích.

502 cũng có thể do trạng thái hội thoại gây ra

Một sự cố gần đây khác của Sub2API liên quan đến các mục reasoning được phát lại (replayed) trong các yêu cầu Responses API nhiều lượt. Thượng nguồn trả về lỗi 404 vì một mục reasoning được tham chiếu không còn khả dụng, trong khi gateway hiển thị lỗi này dưới dạng 502.

Đây là một lý do khác vì sao các lập trình viên không nên xem 502 như một lỗi mạng chung chung.

Vấn đề nền tảng thực ra có thể là:

text

400 Invalid Parameter

hoặc:

text

404 Missing Conversation Item

hoặc:

text

Authentication Failure

hoặc:

text

Upstream Timeout

Nhiệm vụ của gateway là giao tiếp với nhà cung cấp thượng nguồn, và cách chính xác mà một lỗi thượng nguồn được hiển thị phụ thuộc vào cách triển khai gateway.

503 Service Unavailable

Lỗi 503 thường cho biết rằng dịch vụ tạm thời không khả dụng.

Điều này có thể xảy ra khi một nhà cung cấp thượng nguồn đang gặp sự cố ngừng hoạt động, một gateway đã tạm thời vô hiệu hóa một kênh, hoặc hiện tại không có tài khoản nào có thể sử dụng.

Đối với một gateway đa tài khoản, một sự phân biệt quan trọng là liệu:

text

One account → unavailable

hay:

text

Entire channel → unavailable

Nếu chỉ một tài khoản bị lỗi, chuyển đổi dự phòng tự động có thể giải quyết vấn đề.

Nếu mọi tài khoản đều bị lỗi, vấn đề có nhiều khả năng liên quan đến nhà cung cấp, kênh hoặc hạ tầng.

504 Gateway Timeout

Lỗi 504 Gateway Timeout thường có nghĩa là gateway đã chờ một phản hồi thượng nguồn nhưng không nhận được trong thời gian chờ đã cấu hình.

Điều này đặc biệt phổ biến với các yêu cầu AI chạy lâu.

Các tác vụ reasoning lớn, tạo mã, tạo ảnh, lời gọi công cụ và các yêu cầu ngữ cảnh dài có thể tự nhiên mất nhiều thời gian hơn một yêu cầu web thông thường.

Giải pháp có thể bao gồm tăng thời gian chờ thượng nguồn, cải thiện hành vi streaming, kiểm tra độ trễ của nhà cung cấp, hoặc thay đổi mô hình hoặc kênh.

Các lập trình viên nên cẩn thận không xem mọi lần hết thời gian chờ là một lỗi của mô hình. Đôi khi yêu cầu vẫn đang được xử lý ở thượng nguồn trong khi gateway đã ngừng chờ.

Một quy trình khắc phục sự cố lỗi thực tế

Khi một yêu cầu API thất bại, đừng bắt đầu bằng cách thay đổi ngẫu nhiên API key, mô hình hoặc cấu hình.

Một quy trình tốt hơn là xác định lớp gây ra lỗi.

Hãy bắt đầu với mã trạng thái HTTP, sau đó đọc toàn bộ thông báo lỗi. Tiếp theo, xác định xem lỗi bắt nguồn từ client, gateway hay nhà cung cấp thượng nguồn.

Quy trình sau đây hoạt động tốt cho hầu hết các vấn đề API của Claude, Codex, GLM và Kimi:

text

API Request Failed
       ↓
Check HTTP Status
       ↓
Is it 401 / 403?  → Check API Key / Permission
Is it 400?        → Check Parameters / Protocol / Model
Is it 404?        → Check Endpoint / Model / Resource
Is it 429?        → Check Quota / RPM / TPM / Concurrency
Is it 500?        → Check Gateway / Provider Logs
Is it 502?        → Check Upstream Error
Is it 503 / 504?  → Check Provider / Channel / Timeout

Đối với những người vận hành gateway, thông tin gỡ lỗi hữu ích nhất thường bao gồm request ID, mô hình, endpoint, kênh, tài khoản thượng nguồn, mã trạng thái thượng nguồn, thông báo lỗi và độ trễ yêu cầu.

Cách giảm thiểu lỗi API

Cách tốt nhất để giảm lỗi API không phải đơn giản là thêm các lần thử lại.

Một ứng dụng AI mạnh mẽ nên sử dụng đúng endpoint và mô hình, xác thực các tham số yêu cầu, triển khai logic thử lại và backoff hợp lý, duy trì các thiết lập thời gian chờ phù hợp, và tránh gửi các tham số đặc thù của nhà cung cấp đến một thượng nguồn không tương thích.

Các ứng dụng sử dụng công cụ, reasoning, thinking, hoặc các yêu cầu Responses API nhiều lượt cũng nên bảo toàn trạng thái hội thoại liên quan một cách chính xác.

Đối với các hệ thống đa nhà cung cấp, việc chuyển đổi yêu cầu đặc thù cho từng mô hình đặc biệt quan trọng. Claude, Codex, GLM và Kimi có thể cung cấp các API tương tự nhau, nhưng điều đó không có nghĩa là schema yêu cầu và các yêu cầu về hành vi của chúng giống hệt nhau.

Do đó, một gateway đáng tin cậy cần xử lý các khác biệt về giao thức thay vì chỉ đơn giản chuyển tiếp mọi trường mà không thay đổi.

Tại sao một API gateway AI có thể giúp việc xử lý lỗi dễ dàng hơn

Việc xây dựng các tích hợp trực tiếp với nhiều nhà cung cấp AI có thể trở nên phức tạp rất nhanh.

Một đội phát triển có thể cần quản lý riêng biệt Claude API, OpenAI/Codex API, GLM API, Kimi API, thông tin xác thực, tên mô hình, các tham số đặc thù của nhà cung cấp, giới hạn tần suất, các lần thử lại, tính khả dụng của tài khoản và trạng thái dịch vụ.

Một API gateway có thể tập trung hóa một phần của hạ tầng này.

Thay vì duy trì nhiều tích hợp độc lập, các lập trình viên có thể sử dụng một giao diện API thống nhất và chọn mô hình hoặc nhóm cần thiết.

Điều này đặc biệt hữu ích cho các ứng dụng lập trình AI, nơi các lập trình viên có thể muốn dùng Claude cho reasoning, Codex cho kỹ thuật phần mềm, Kimi cho các tác vụ ngữ cảnh lớn, và GLM cho các khối lượng công việc nhạy cảm về chi phí.

Sử dụng DDShub khi bạn không muốn tự khắc phục mọi sự cố

Đối với các lập trình viên sử dụng API AI thông qua một gateway, một lỗi không phải lúc nào cũng là thứ có thể giải quyết từ phía client.

Đôi khi vấn đề thực sự nằm ở thượng nguồn. Đôi khi cần chuyển đổi kênh. Đôi khi cần loại bỏ một tài khoản khỏi vòng luân chuyển. Đôi khi một yêu cầu cần chuyển đổi giao thức. Đôi khi nhà cung cấp đã thay đổi hành vi API của họ.

Đây là lúc DDShub có thể hữu ích.

DDShub cung cấp quyền truy cập API đến nhiều mô hình AI, bao gồm Claude, Codex, GLM và Kimi, thông qua một nền tảng thống nhất. Thay vì quản lý riêng lẻ nhiều nhà cung cấp thượng nguồn và khắc phục sự cố cho từng tích hợp đặc thù của nhà cung cấp, các lập trình viên có thể sử dụng DDShub làm lớp truy cập API.

Quan trọng hơn, DDShub cung cấp hỗ trợ khách hàng cho việc khắc phục sự cố API. Khi một lỗi không thể được giải quyết đơn giản bằng cách thay đổi cấu hình client, người dùng có thể cung cấp thông báo lỗi, mô hình, endpoint và thông tin yêu cầu cho đội hỗ trợ để vấn đề có thể được điều tra từ phía gateway và thượng nguồn.

Điều này đặc biệt hữu ích cho các lập trình viên sử dụng Claude Code, Codex, Cursor, VS Code, OpenClaw hoặc các công cụ lập trình AI khác, nơi một lỗi API có thể làm gián đoạn một quy trình phát triển đang diễn ra.

Bạn có thể khám phá các mô hình khả dụng và các tùy chọn API hiện tại trên website của DDShub: DDShub AI Models

Để biết thông tin về tích hợp API: DDShub API Documentation

Lời kết

Lỗi API là một phần bình thường của việc làm việc với hạ tầng AI hiện đại, nhưng chúng trở nên dễ giải quyết hơn nhiều một khi các lập trình viên hiểu được chuỗi yêu cầu.

Lỗi 400 thường có nghĩa là yêu cầu cần được xem xét. Lỗi 401 chỉ đến vấn đề xác thực, trong khi 403 thường cho thấy một vấn đề về quyền. Lỗi 404 thường có nghĩa là một endpoint hoặc tài nguyên không thể được tìm thấy, và 429 đòi hỏi điều tra về giới hạn tần suất, hạn ngạch, tính đồng thời hoặc công suất mô hình.

Lỗi quan trọng nhất cần điều tra cẩn thận thường là 502.

Một lỗi 502 Bad Gateway không nhất thiết có nghĩa là gateway bị hỏng. Như các sự cố thực tế của Sub2API cho thấy, một lỗi 400, 404 phía thượng nguồn, một tham số không được hỗ trợ, trạng thái hội thoại không hợp lệ, hoặc vấn đề định tuyến tài khoản cuối cùng có thể xuất hiện với client dưới dạng 502.

Đối với các lập trình viên làm việc với Claude, Codex, GLM hoặc Kimi, thói quen khắc phục sự cố hữu ích nhất do đó là nhìn xa hơn mã trạng thái và xác định lỗi thực sự đã xảy ra ở đâu trong chuỗi yêu cầu.

Nếu bạn không muốn dành hàng giờ để tự mình điều tra các lỗi đặc thù của nhà cung cấp, các khác biệt giao thức, các tài khoản thượng nguồn và nhật ký gateway, một nền tảng API như DDShub có thể cung cấp thêm một lớp hỗ trợ, với nhiều mô hình khả dụng thông qua một môi trường API thống nhất và dịch vụ khách hàng sẵn sàng khi một vấn đề đòi hỏi điều tra vượt ra ngoài cấu hình client.

Trong phát triển AI, một API đáng tin cậy không chỉ là về việc liệu một yêu cầu có thành công hay không. Nó còn là về việc bạn có thể hiểu và giải quyết yêu cầu nhanh đến mức nào khi nó thất bại.