> ## Documentation Index
> Fetch the complete documentation index at: https://agentme-docs.vipcrm.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Lỗi

> Định dạng lỗi và danh sách mã.

Mọi phản hồi không thành công có cùng dạng:

```json theme={null}
{ "error": { "code": "RATE_LIMITED", "message": "...", "details": { "limit_type": "channel" }, "request_id": "..." } }
```

Gửi kèm `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](https://agentme-docs.vipcrm.net/rate-limits-and-anti-ban.md) |
| 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` |

> [!NOTE]
>
> 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.