Giới hạn và lỗi
Giới hạn số lần gọi và số bản ghi, tiêu đề báo giới hạn, mã lỗi của API của cổng.
Giới hạn
Giới hạn bảo vệ cổng của trường khỏi việc gửi dồn dập (theo OWASP API Security, mục API4: tiêu thụ tài nguyên không giới hạn). Các số dưới đây là mặc định cho mỗi kết nối; cần mức khác thì liên hệ nhà trường.
| Giới hạn | Mặc định |
|---|---|
| Lời gọi đọc | 600 mỗi phút |
| Lời gọi ghi | 60 mỗi phút |
| Lời gọi cùng lúc | 4 |
| Bản ghi gửi lên | 2.000 mỗi phút, 50.000 mỗi ngày |
| Bản ghi cả trường nhận (mọi kết nối cộng lại) | 5.000 mỗi phút |
| Sinh viên mỗi lần gửi theo lô | 500 |
| Thân JSON | 5 MB |
| Gói CSV OneRoster | 20 MB, 50.000 dòng mỗi tệp |
| Lượt xử lý chờ hoặc đang chạy của một trường | 4 |
Lượt xử lý chạy dần theo giới hạn bản ghi, nên một gói lớn có thể mất vài phút.
Tiêu đề báo giới hạn
Mỗi phản hồi có tiêu đề theo bản thảo IETF RateLimit header fields for HTTP:
RateLimit-Policy: "read";q=600;w=60
RateLimit: "read";r=596;t=42q: số lần cho phép trongwgiây.r: số lần còn lại.t: số giây tới khi tính lại.- Lệnh ghi có thêm chính sách
"records"cho số bản ghi mỗi phút.
Vượt giới hạn trả 429 Too Many Requests kèm Retry-After (số giây). Hãy đợi đúng thời gian đó rồi gửi lại; gửi lệnh ghi kèm Idempotency-Key để gửi lại không tạo việc trùng.
Lỗi
Lỗi theo Problem Details (RFC 9457), kiểu application/problem+json:
{
"type": "urn:ttdn:problem:invalid-request",
"title": "The request is not valid",
"status": 422,
"detail": "Some students are not valid; nothing was queued.",
"instance": "/integration/v1/students/batch",
"errors": [{ "index": 3, "ref": "SV2026004", "message": "studentCode and name are required." }]
}Dựa vào type để xử lý; title và detail (tiếng Anh) để đọc.
| Mã HTTP | type (urn:ttdn:problem:...) | Khi nào |
|---|---|---|
| 401 | unauthorized | Thiếu mã, mã sai, hết hạn, đã thu hồi, hoặc mã của trường khác |
| 403 | insufficient-scope | Mã không có quyền cho điểm truy cập này |
| 403 | ip-not-allowed | Gọi từ địa chỉ mạng không nằm trong danh sách nhà trường cho phép |
| 404 | not-found | Không có đợt, sinh viên hay lượt xử lý này |
| 409 | conflict, code-taken, login-name-taken, declared-code | Dữ liệu trỏ tới tài khoản khác (email, mã sinh viên, tên đăng nhập đã thuộc người khác) |
| 409 | season-closed | Đưa sinh viên vào đợt đã đóng |
| 413 | too-large | Thân yêu cầu quá lớn hoặc quá 500 sinh viên |
| 422 | invalid-request | Dữ liệu không hợp lệ; errors liệt kê từng dòng |
| 422 | invalid-package | Gói CSV OneRoster không đọc được |
| 422 | idempotency-key-reused, invalid-idempotency-key | Idempotency-Key đã dùng cho nội dung khác, hoặc dài quá 255 ký tự |
| 429 | rate-limited | Vượt giới hạn; đợi theo Retry-After |
| 500 | internal-error | Lỗi phía cổng; thử lại sau, vẫn lỗi thì báo nhà trường |
| 503 | busy | Trường đã có 4 lượt chờ; đợi theo Retry-After |
Nhà trường thấy gì
Ở trang Kết nối hệ thống, mục Theo dõi của mỗi kết nối cho nhà trường thấy số lần gọi mỗi ngày trong 30 ngày (thành công, lỗi do yêu cầu, lỗi hệ thống), số bản ghi đã gửi và các lỗi gần đây. Cổng chỉ đếm số lượng, không lưu nội dung yêu cầu. Số liệu theo ngày giữ 13 tháng, lỗi gần đây giữ 30 ngày.