Cơ sở kiến thức GetMyBot

Lỗi API

Đọc lỗi API, biết khi nào cần sửa yêu cầu hoặc thử lại. Cách lặp lại thanh toán và gửi hàng loạt mà không tạo bản trùng.

Trên trang này

Nếu yêu cầu thất bại, hãy xem mã HTTP trước: 401 báo vấn đề về quyền truy cập, còn 429 nghĩa là gửi quá thường xuyên. Trường error trong câu trả lời nêu nguyên nhân cụ thể. Yêu cầu thành công trả dữ liệu trực tiếp, không có lớp bọc chung.

Định dạng lỗi

Khi có lỗi, nội dung phản hồi là JSON object với một trường error chứa thông báo có thể đọc được:

{"error":"reaction not found"}

Hãy ưu tiên dựa vào mã trạng thái HTTP, còn văn bản error dùng cho log và gợi ý cho người dùng.

Mã trạng thái

  • 200 OK — yêu cầu thành công, trong nội dung là dữ liệu.
  • 201 Created — tài nguyên mới được tạo (một số endpoint POST).
  • 204 No Content — thành công không có nội dung (một số thao tác xóa).
  • 400 Bad Request — nội dung hoặc tham số yêu cầu không hợp lệ.
  • 401 Unauthorized — token thiếu, sai hoặc hết hạn; hoặc route không thể truy cập bằng token cá nhân.
  • 402 Payment Required — hành động bị giới hạn bởi gói cước hoặc hạn mức (ví dụ: lưu trữ media riêng yêu cầu premium).
  • 403 Forbidden — token thiếu phạm vi cần thiết hoặc chủ token thiếu quyền trong tài khoản quản trị (missing cabinet right, xem Tài khoản của token).
  • 404 Not Found — tài nguyên không tìm thấy hoặc không thuộc về bạn.
  • 409 Conflict — xung đột trạng thái, như giá trị duy nhất bị trùng; cũng có thể nghĩa là yêu cầu với Idempotency-Key đó đang chạy, xem bên dưới.
  • 413 Payload Too Large — nội dung quá lớn (xem giới hạn); yêu cầu có Idempotency-Key có giới hạn riêng thấp hơn là 64 KiB.
  • 422 Unprocessable Entity — nội dung đúng cú pháp nhưng sai quy tắc nghiệp vụ; cũng có thể nghĩa là cùng Idempotency-Key được dùng với nội dung khác.
  • 429 Too Many Requests — vượt quá giới hạn yêu cầu (xem giới hạn).
  • 500 Internal Server Error — lỗi nội bộ máy chủ; hãy thử lại sau.

Cách xử lý

Coi mã 2xx là thành công. Với 401/403, kiểm tra token, phạm vi và quyền trong tài khoản quản trị. Với 429 và 5xx, có thể thử lại sau khoảng chờ tăng dần.

Với 4xx khác 429, thường phải sửa yêu cầu trước khi thử lại. Một ngoại lệ: 409 ở yêu cầu có Idempotency-Key nghĩa là cùng thao tác đang chạy. Đừng bỏ cuộc rồi coi thanh toán hoặc lượt gửi là thất bại. Hãy chờ theo Retry-After và thử lại với chính khóa cũ.

Lặp lại thao tác thanh toán: Idempotency-Key

Khóa phải là UUID chuẩn viết thường và có dấu gạch nối, ví dụ 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d. Định dạng khác bị từ chối với mã 400.

Áp dụng ở đâu?

Header này không bắt buộc, nhưng được xử lý với các thao tác có thể tốn tiền hoặc gửi tới nhiều người:

  • POST /api/billing/topup: nạp số dư;
  • POST /api/billing/subscribe: đăng ký gói;
  • POST /api/bots/{botID}/reactions/{reactionID}/broadcast: bắt đầu gửi hàng loạt.

Với hai thao tác gửi tin từ giao diện nhân viên, header lại bắt buộc; thiếu nó bị từ chối với mã 400:

  • POST /api/bots/{botID}/users/{userID}/dialog/messages;
  • POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates.

Ở các đường dẫn khác, header bị bỏ qua. Đừng coi nó là cách chống trùng áp dụng cho toàn API: ngoài danh sách trên, yêu cầu lặp là thao tác thứ hai.

Máy chủ trả gì?

  • Cùng khóa, cùng nội dung, thao tác đã xong: trả lại mã và nội dung đã lưu từ lần đầu, kèm Idempotent-Replay: true. Thao tác chỉ chạy một lần. Bản ghi được giữ một tuần.
  • Cùng khóa, thao tác còn chạy: trả 409 và Retry-After. Chờ rồi thử lại với khóa cũ. Khóa mới có thể tạo khoản trừ thứ hai.
  • Cùng khóa, nội dung khác: trả 422. Hãy dùng khóa mới cho thao tác thực sự khác.
  • Nội dung lớn hơn 64 KiB: trả 413. Các thao tác này thường có nội dung nhỏ; hãy kiểm tra dữ liệu gửi đi.

Máy chủ không ghi nhớ lỗi 5xx, 408, 425 hoặc 429 theo khóa. Những lỗi này cho biết thao tác chưa được thực hiện, nên thử lại bằng cùng khóa sẽ chạy thao tác đúng lúc có thể.

Cách sử dụng

  1. Tạo UUID trước lần gửi đầu và lưu cùng tác vụ.
  2. Gửi yêu cầu với khóa đó.
  3. Nếu mất kết nối, hết thời gian chờ, nhận 5xx hoặc 429, thử lại bằng cùng khóa.
  4. Nếu nhận 409, chờ theo Retry-After rồi thử lại bằng khóa cũ.
  5. Chỉ tạo khóa mới cho một thao tác mới thực sự.

Nếu tạo khóa mới ở mỗi lần thử, header sẽ không ngăn được bản trùng: máy chủ coi mỗi lần là một thao tác riêng.

Lỗi AI và thiết lập kịch bản

Managed AI có các mã nguyên nhân not_available (tính năng không khả dụng), not_entitled (không có quyền), budget_exceeded (hết ngân sách), rate_limited (quá nhiều yêu cầu), provider_unavailable (dịch vụ AI không khả dụng) và schema_validation_failed (câu trả lời sai cấu trúc). Chỉ thử lại khi câu trả lời cho phép, dùng cùng Idempotency-Key. Với lỗi 4xx khác 429, hoặc lỗi kiểm tra cấu trúc, hãy sửa yêu cầu; đổi nhà cung cấp AI không giải quyết được.

Nếu Copilot trả stale_base, đề xuất sửa phản ứng đã cũ: tạo lại trên cấu trúc hiện tại. Sửa quy tắc phân tích trả 409 nếu yêu cầu khác đã thay đổi trước. Việc tính lại phân tích và tái hiện lần chạy là tác vụ có giới hạn; kiểm tra trạng thái tác vụ đã mở trước khi tạo tác vụ mới. Kiểm tra kết nối Meta trả mã nguyên nhân để tìm lỗi, không đưa nội dung trả lời của Meta hoặc token truy cập vào thông báo lỗi.

Tiếp theo