Xử lý giới hạn tốc độ và lỗi máy chủ

Xử lý phản hồi 429

Yêu cầu bị giới hạn tốc độ trả về 429 Too Many Requests với detail.status được đặt thành rate_limit_exceeded. Đọc header phản hồi trước khi thử lại:

• Retry-After cho biết thời gian chờ tối thiểu, tính bằng giây, đối với yêu cầu bị từ chối.
• X-RateLimit-Limit cho biết giới hạn của nhóm.
• X-RateLimit-Remaining cho biết số yêu cầu còn lại.
• X-RateLimit-Reset cho biết thời điểm nhóm được đặt lại.

Chờ đủ thời gian theo Retry-After, rồi thử lại với thời gian chờ tăng theo cấp số nhân và thêm độ lệch ngẫu nhiên. Giảm số yêu cầu chạy song song và đưa công việc vào hàng đợi thay vì gửi dồn dập ngay khi cửa sổ giới hạn được đặt lại.

Xử lý lỗi máy chủ

Với phản hồi 500, phần thân công khai chứa lỗi chung và request_id; thông tin chi tiết về ngoại lệ nội bộ không được trả về. Phản hồi 503 có thể cho biết một dịch vụ cần thiết tạm thời không khả dụng.

Thử lại các yêu cầu chỉ đọc với thời gian chờ có giới hạn. Trước khi thử lại yêu cầu tạo, cập nhật, thanh toán hoặc thao tác khác làm thay đổi trạng thái, hãy xác định lần thử đầu tiên đã hoàn tất hay chưa. Timeout hoặc phản hồi 5xx không chứng minh thao tác đã thất bại; gửi lại ngay có thể tạo công việc trùng lặp.

Lưu thông tin chẩn đoán

Ghi lại dấu thời gian, phương thức, đường dẫn, trạng thái, phần thân phản hồi và X-Request-Id. Tuyệt đối không ghi nhật ký giá trị x-api-key. Dừng tự động thử lại sau một số lần nhỏ có giới hạn và đưa lỗi ra để xem xét.