Bảng tra mã lỗi Email API
Tra mã lỗi Email API trả về, biết lỗi thuộc về yêu cầu của bạn hay về hệ thống, và biết mã nào nên thử lại còn mã nào thì không.
Tra theo mã bạn nhận được. Cần đi từ triệu chứng thay vì từ mã thì xem Xử lý sự cố Email API.
Mọi phản hồi lỗi có cùng hình dạng, và message chính là mã tra trong bảng dưới:
{ "success": false, "statusCode": 403, "message": "DOMAIN_NOT_VERIFIED" }Nhóm mã HTTP
Đọc chữ số đầu tiên trước khi đọc mã chi tiết — nó quyết định có nên thử lại hay không.
| Mã | Ý nghĩa | Thử lại? |
|---|---|---|
202 | Đã nhận và đưa vào hàng đợi. Lưu id để tra cứu về sau | — |
400 | Yêu cầu sai — thiếu trường hoặc sai định dạng | Không, sửa yêu cầu trước |
401 | Khoá sai, đã thu hồi, hoặc gọi từ IP nằm ngoài giới hạn IP của khoá | Không |
403 | Khoá hợp lệ nhưng không được phép làm việc này | Không |
404 | Không tìm thấy id hoặc địa chỉ cần tra | Không |
410 | Nội dung đã hết hạn lưu | Không |
413 | Thư vượt trần dung lượng | Không, giảm dung lượng |
422 | Yêu cầu hợp lệ nhưng không xử lý được — người nhận nằm trong danh sách chặn (RECIPIENT_SUPPRESSED) hoặc đã được xác minh là không tồn tại (RECIPIENT_PLATFORM_SUPPRESSED) | Không |
429 | Vượt hạn mức hoặc vượt tốc độ | Có, chờ rồi gửi lại |
500 | Lỗi phía hệ thống | Có, giãn dần thời gian chờ |
503 | Hạ tầng tạm không sẵn sàng | Có, giãn dần thời gian chờ |
Quy tắc gọn: 4xx là lỗi của yêu cầu, trừ 429. Chỉ 429, 500 và 503 đáng thử lại — thử lại
một 400 sẽ cho ra đúng 400 đó mãi mãi.
Lỗi về người nhận và nội dung
Toàn bộ nhóm này xảy ra trước khi trừ hạn mức. Thư bị từ chối không tính vào hạn mức ngày hay tháng của bạn.
| Mã | HTTP | Khi nào gặp |
|---|---|---|
INVALID_TO | 400 | Danh sách to rỗng sau khi loại địa chỉ trùng |
INVALID_RECIPIENT | 400 | Một địa chỉ trong to, cc hoặc bcc sai định dạng |
TOO_MANY_RECIPIENTS | 400 | Tổng to + cc + bcc vượt 50 địa chỉ |
CONTENT_REQUIRED | 400 | Thiếu cả html lẫn text. Dùng mẫu email thì mã này nghĩa là mẫu cho ra nội dung rỗng |
VALIDATION_ERROR | 400 | Yêu cầu sai cấu trúc. Phản hồi kèm trường errors chỉ đúng chỗ sai |
Địa chỉ trùng nhau bị gộp trước khi đếm, nên gửi cùng một địa chỉ hai lần không làm bạn chạm trần sớm hơn.
Lỗi về file đính kèm
| Mã | HTTP | Khi nào gặp |
|---|---|---|
INVALID_ATTACHMENT | 400 | Trường content không phải chuỗi base64 hợp lệ |
TOO_MANY_ATTACHMENTS | 400 | Quá 10 file trong một thư |
INVALID_FILENAME | 400 | Tên file rỗng, là . hoặc .., hoặc dài quá 255 byte |
ATTACHMENT_TYPE_BANNED | 400 | Đuôi file nằm trong danh sách bị cấm — .exe, .bat, .cmd, .js, .vbs, .scr, .pif và nhiều đuôi thực thi khác |
MESSAGE_TOO_LARGE | 413 | Thư vượt trần 25 MB. Phản hồi kèm limitBytes và actualBytes để bạn biết vượt bao nhiêu |
ATTACHMENT_EXPIRED | 410 | Tải lại file đính kèm sau khi đã hết hạn lưu nội dung |
Đường dẫn thư mục trong tên file không bị từ chối — hệ thống tự cắt lấy phần tên file rồi mới kiểm tra độ dài.
Danh sách đuôi bị cấm áp cho đuôi file, không phải nội dung bên trong. Cần gửi loại file này thì nén lại rồi gửi, hoặc đặt file ở nơi tải xuống và gửi liên kết.
Lỗi về quyền và tên miền
| Mã | HTTP | Khi nào gặp |
|---|---|---|
DOMAIN_NOT_VERIFIED | 403 | Tên miền trong from chưa hoạt động, không tồn tại, hoặc thuộc dịch vụ khác |
DOMAIN_SCOPE_VIOLATION | 403 | Khoá gửi bị gắn với một tên miền khác với tên miền trong from |
SENDING_KEY_REQUIRED | 403 | Dùng Account Key để gửi thư. Gửi thư chỉ nhận Sending Key |
ACCOUNT_KEY_REQUIRED | 403 | Dùng khoá gửi cho lời gọi quản lý tài khoản. Hai loại khoá không thay thế nhau |
ACCOUNT_SUSPENDED | 403 | Tài khoản dịch vụ đang tạm ngưng |
COMPLAINT_SUPPRESSION_LOCKED | 403 | Địa chỉ vào danh sách chặn do người nhận báo thư rác. Bạn không tự gỡ được — liên hệ bộ phận hỗ trợ |
BOUNCE_SUPPRESSION_LOCKED | 403 | Địa chỉ vào danh sách chặn do nơi nhận trả lời địa chỉ không tồn tại. Bạn không tự gỡ được — liên hệ bộ phận hỗ trợ |
Ba tình huống, một câu trả lời
DOMAIN_NOT_VERIFIED trả về y hệt nhau cho ba trường hợp: tên miền không tồn tại, tên miền chưa
xác minh xong, và tên miền thuộc dịch vụ khác. Đây là chủ ý — phản hồi khác nhau sẽ cho phép người
ngoài dò xem tên miền nào đang có trên nền tảng. Kiểm trạng thái thật ở màn hình Tên miền gửi.
Lỗi về hạn mức và hệ thống
| Mã | HTTP | Khi nào gặp | Xử lý |
|---|---|---|---|
429 | 429 | Hết hạn mức ngày hoặc chu kỳ 30 ngày, hoặc gửi dồn dập trong thời gian ngắn | Xem bên dưới |
QUOTA_BACKEND_UNAVAILABLE | 503 | Hệ thống đếm hạn mức tạm không phản hồi | Chờ rồi gửi lại |
ENQUEUE_FAILED | 503 | Không đưa được thư vào hàng đợi | Chờ rồi gửi lại |
ATTACHMENT_UPLOAD_FAILED | 503 | Lưu file đính kèm thất bại. Thư không được tạo và hạn mức đã hoàn lại | Gửi lại |
ATTACHMENT_STORAGE_UNAVAILABLE | 503 | Kho file đính kèm tạm không sẵn sàng | Chờ rồi gửi lại |
429 có hai nguyên nhân và cách xử lý ngược nhau:
- Vượt tốc độ — chờ vài giây rồi gửi lại là xong. Số thư còn lại trong ngày không đổi.
- Hết hạn mức ngày — gửi lại bao nhiêu lần cũng vẫn
429cho tới nửa đêm. Đối chiếu số đã gửi trên màn hình Tổng quan để biết bạn đang gặp cái nào.
Hạn mức thật của tài khoản nằm ở khối Hạn mức tài khoản Email API trên màn hình Tổng quan — xem Đọc trang Tổng quan của từng dịch vụ. Trần kỹ thuật của một email nằm ở mục Giới hạn & Lỗi trong Email API → Hướng dẫn ở bảng điều khiển.
Cách thử lại cho đúng
Với 429, 500 và 503, giãn dần thời gian chờ thay vì gửi lại ngay: 1 giây, 2 giây, 4 giây, 8
giây. Gửi lại ngay lập tức trong vòng lặp là cách nhanh nhất để tự khoá chính mình.
Đặt trần số lần thử. Sau 5 lần vẫn lỗi thì ghi lại yêu cầu và báo bộ phận hỗ trợ, đừng thử vô hạn.
Với 202, thư mới chỉ vào hàng đợi. Kết quả giao tới người nhận đến sau, qua màn hình
Thống kê & Nhật ký hoặc qua webhook.