Giới hạn tốc độ API và các phương pháp hay nhất

Mỗi khóa API của Ody nhận được 600 yêu cầu mỗi phút trên /v1/api/* và điểm cuối MCP — hãy đọc các tiêu đề RateLimit-* trên mỗi phản hồi và lùi lại với giá trị Retry-After khi bạn nhận được 429.

Giới hạn hoạt động như thế nào

• Giới hạn là cho mỗi khóa, được tính trong một cửa sổ 60 giây cố định. Các yêu cầu không có khóa hợp lệ sẽ bị giới hạn theo IP thay thế.
• Mỗi phản hồi — thành công hoặc lỗi — đều chứa ba tiêu đề chuẩn:
  • RateLimit-Limit — ngân sách mỗi phút của bạn (600).
  • RateLimit-Remaining — số yêu cầu còn lại trong cửa sổ hiện tại.
  • RateLimit-Reset — số giây cho đến khi cửa sổ đặt lại.
• Vượt quá giới hạn sẽ trả về 429 với mã lỗi resource_exhausted và tiêu đề Retry-After (giây). Chờ ít nhất khoảng thời gian đó trước khi thử lại.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

Duy trì dưới giới hạn

• Theo dõi RateLimit-Remaining và chủ động giảm tốc độ khi nó gần về 0, thay vì phản ứng với các lỗi 429.
• Sử dụng webhook thay vì thăm dò. Đăng ký một điểm cuối cho các sự kiện như message.received và Ody sẽ đẩy hoạt động đến bạn — xem Nhận webhook và xác minh chữ ký. Nếu bạn phải thăm dò, mỗi 10–30 giây là đủ cho một hộp thư đến dùng chung.
• Thử lại với chiến lược lùi lũy thừa và jitter khi gặp lỗi 429 và 5xx, giới hạn số lần thử lại. Tuân thủ Retry-After khi có. Đối với các lần gửi, kết hợp thử lại với Idempotency-Key để tránh gửi trùng lặp — xem Phân trang, tính bất biến và xử lý lỗi.
• Yêu cầu các trang lớn hơn (?limit= lên đến mức tối đa của mỗi điểm cuối) thay vì nhiều trang nhỏ khi đồng bộ hóa dữ liệu.

Các phương pháp hay nhất về bảo mật khóa

• Giới hạn phạm vi của mỗi khóa ở mức tối thiểu cần thiết. Bỏ chọn các phạm vi khi tạo — một bảng điều khiển chỉ đọc các cuộc hội thoại chỉ nên giữ conversations:read. Xem Lấy khóa API Ody của bạn.
• Sử dụng khóa thử nghiệm ở mọi nơi mà tin nhắn thực tế có thể gây lỗi. Môi trường phát triển và CI nên chạy trên các khóa ody_test_… để các tin nhắn gửi đi được mô phỏng — xem Xây dựng an toàn với chế độ thử nghiệm.
• Một khóa cho mỗi tích hợp. Các khóa riêng biệt cho Zapier, máy chủ của bạn và một trợ lý AI có nghĩa là bạn có thể thu hồi một khóa mà không làm hỏng các khóa khác, và cột lần sử dụng cuối cùng trong Cài đặt → API nhà phát triển vẫn có ý nghĩa.
• Giữ khóa ở phía máy chủ. Không bao giờ nhúng khóa vào ứng dụng di động, JavaScript trình duyệt hoặc tài liệu dùng chung — bất kỳ ai có khóa đều có thể hành động như người tạo ra nó trong phạm vi của nó.
• Xoay vòng và cắt tỉa. Thu hồi các khóa bạn không còn sử dụng. Vì văn bản gốc chỉ hiển thị một lần, xoay vòng có nghĩa là tạo một khóa mới, triển khai nó, sau đó thu hồi khóa cũ.

Các bài viết liên quan

• Tổng quan API và xác thực
• Phân trang, tính bất biến và xử lý lỗi
• Nhận webhook và xác minh chữ ký
• Xây dựng an toàn với chế độ thử nghiệm