Ai từng phát hành một bot Discord đều đã gặp điều này: một ngày thứ Ba bình thường, rồi đột nhiên increased api errors xuất hiện khắp nơi và một nửa lệnh của bạn thất bại. Google Trends ghi nhận cụm từ này là một từ khóa "bùng nổ" vào giữa năm 2026; nó xảy ra đủ thường xuyên để người dùng cuối tìm kiếm trực tiếp. Đây là cách vượt qua nó, và những bài học mà Server API của Noxyr rút ra từ đó.

A request gets a 429, waits out a countdown, then retries and succeeds with a 200. Server 429 200 3 2 1 Retry-After

Ba kiểu lỗi lớn nhất của Discord API

  • Sự cố toàn cầu / sự cố một phần: hiển thị trên discordstatus.com. Triệu chứng: bất kỳ yêu cầu nào cũng có thể thất bại, gateway có thể bị rớt, độ trễ tăng vọt ở khắp nơi.
  • 429 Too Many Requests: bạn đã vượt giới hạn của một bucket. Discord trả về header Retry-After cho biết chính xác bạn cần chờ bao lâu.
  • Gateway invalid session: phiên WebSocket của bạn đã cũ. Kết nối lại bằng resume token; nếu thất bại, hãy identify lại từ đầu.

Xây dựng cho lúc thất bại, không chỉ cho lúc thuận lợi

  • Tôn trọng Retry-After. Đừng tự thử lại theo bộ đếm giờ riêng. Hãy chờ đúng khoảng thời gian Discord báo, rồi thử lại một lần. Các bot liên tục đập vào 429 sẽ bị cấm.
  • Exponential backoff kèm jitter. Với lỗi 5xx, chờ 1s, 2s, 4s, 8s, cộng thêm một độ lệch ngẫu nhiên nhỏ để một loạt lần khởi động lại không đổ xô cùng lúc.
  • Ngắt mạch các lệnh không quan trọng. Nếu bot của bạn đăng bản tin hàng tuần và Discord API đang suy giảm, hãy bỏ qua lần chạy này thay vì dồn thêm tải. Bản tin có thể chờ; sự cố thì không.
  • Cache mọi thứ không cần thời gian thực. Tên máy chủ, danh sách kênh, ID vai trò, hãy cache cục bộ. Trong lúc sự cố, dữ liệu đã cache giúp bạn tiếp tục phục vụ.
  • Hiển thị trạng thái. Nếu lệnh của bot thất bại vì Discord đang ngừng hoạt động, hãy báo cho người dùng. Một dòng "Discord hiện đang gặp sự cố" tốt hơn là timeout im lặng.

Server API của Noxyr áp dụng những bài học này như thế nào

Server API của Noxyr không phải là Discord API; nó đọc từ cơ sở dữ liệu riêng của mình, nhưng các nguyên tắc tương tự vẫn áp dụng và đã định hình thiết kế của nó:

  • Lỗi có thể đoán trước: mọi lỗi đều là JSON với một mã error ổn định. Không có HTML, không có định dạng thay đổi.
  • Header giới hạn tốc độ: các header RateLimit-* chuẩn hóa để client lùi lại trước khi chạm 429.
  • Suy giảm có kiểm soát: endpoint /api/v1/server chuyển sang dữ liệu guild đã cache khi việc lấy dữ liệu từ Discord bên dưới thất bại.
  • Không có lỗi dây chuyền: mỗi endpoint thất bại độc lập. Discord ngừng hoạt động không làm hỏng endpoint phân tích vé của bạn, vì nó đọc từ Mongo chứ không phải từ Discord.
  • Công tắc ngắt tức thì: vô hiệu hóa một key hoặc một phạm vi có hiệu lực ngay ở yêu cầu tiếp theo, không cần khởi động lại.

Quy trình khi Discord gặp trục trặc

  • 1. Kiểm tra discordstatus.com trước, có phải chỉ mình bạn gặp không?
  • 2. Xem nhật ký lỗi của chính bạn: 429, 5xx, gateway bị ngắt kết nối.
  • 3. Nếu là lỗi của Discord: tạm dừng các thao tác ghi không quan trọng, tôn trọng Retry-After, và chờ qua đợt này.
  • 4. Nếu là lỗi của bạn: kiểm tra các lần deploy gần đây, việc vô hiệu hóa cache, các tính năng mới.
  • 5. Thông báo. Một ghi chú ngắn, trung thực trong kênh hỗ trợ sẽ ngăn được 100 báo cáo trùng lặp.

Thêm về lớp API: Server API của Noxyr, Discord API so với Noxyr API, nguyên tắc thiết kế API.