{ "error": { "code": "RATE_LIMITED", "message": "...", "details": { "limit_type": "channel" }, "request_id": "..." } }
request_id khi cần hỗ trợ.
| HTTP | code | Khi nào và cách xử lý |
|---|---|---|
| 400 | VALIDATION_ERROR | Tham số sai. Sửa theo message |
| 401 | UNAUTHORIZED | Thiếu, sai hoặc đã thu hồi key |
| 403 | FORBIDDEN_SCOPE | Key thiếu scope. Tạo key có scope cần |
| 403 | FORBIDDEN | Không được phép (không có workspace, hoặc cần phiên đăng nhập web) |
| 404 | NOT_FOUND | Không có id đó trong workspace của bạn |
| 409 | ACCOUNT_NOT_READY | Nick chưa sẵn sàng. details.status cho biết trạng thái (channel_disabled = quản trị viên đã tắt kênh tạm thời) |
| 409 | MEDIA_NOT_READY | Media đang lưu. Thử lại sau vài giây |
| 409 | CONFLICT | Idempotency-Key đang xử lý hoặc dùng lại với body khác |
| 410 | GONE | Media quá 30 ngày đã bị xoá |
| 413 | PAYLOAD_TOO_LARGE | Upload vượt 25MB |
| 415 | UNSUPPORTED_MEDIA_TYPE | Loại file bị chặn (ví dụ file thực thi) |
| 422 | CAPABILITY_NOT_SUPPORTED | Kênh không hỗ trợ hành động này |
| 422 | BULK_CONTENT_BLOCKED | Cùng một nội dung đã gửi cho quá nhiều người nhận khác nhau trong 1 giờ. Đổi nội dung hoặc chờ, xem Rate limit và anti-ban |
| 429 | RATE_LIMITED | Có Retry-After. details.limit_type: api (600/phút/key) hoặc channel (giới hạn anti-ban) |
| 502 | UPSTREAM_ERROR | Kênh (Zalo) báo lỗi. Không retry mù |
| 503 | SERVICE_UNAVAILABLE | Tạm thời không khả dụng (ví dụ chưa cấu hình lưu media) |
| 502 | UPSTREAM_ERROR | Kênh báo lỗi. error.details.upstream_code (nếu có) là mã kênh đã lọc ([A-Z0-9_], tối đa 40 ký tự), không bao giờ là nội dung lỗi gốc |
| 504 | UPSTREAM_TIMEOUT | Kênh không trả lời kịp. Với gửi tin, kiểm tra lại hội thoại hoặc gửi lại cùng client_msg_id |
Vượt giới hạn là bị từ chối ngay (429), không xếp hàng gửi trễ. Agent tự quyết định gửi lại sau
Retry-After.