Lỗi & giới hạn
Định dạng lỗi, bảng mã lỗi thường gặp và giới hạn lưu lượng.
Định dạng lỗi
Mọi lỗi trả về application/problem+json:
{
"type": "about:blank",
"title": "Unprocessable Entity",
"status": 422,
"code": "input_too_long",
"detail": "Nội dung vượt 2000 ký tự",
"request_id": "01JB…",
"errors": [{ "field": "input.text", "code": "too_long", "message": "…" }]
}Xử lý theo code (ổn định), không theo detail (có thể đổi câu chữ). Gửi kèm request_id khi liên hệ hỗ trợ.
Core API
| HTTP | code | Nguyên nhân → cách xử lý |
|---|---|---|
| 401 | — | Thiếu/sai/đã thu hồi API key |
| 403 | not_whitelisted, no_subscription, end_user_blocked | Người dùng không được phép, chưa có gói, hoặc bị khoá trên Cổng đối tác |
| 403 | orchestrator_not_allowed | Trợ lý điều phối không gắn với App |
| 409 | — | Phiên đang xử lý lượt trước / cùng Idempotency-Key đang xử lý — chờ rồi thử lại |
| 413 | — | Âm thanh quá lớn/dài |
| 422 | validation_failed, input_too_long | Dữ liệu không hợp lệ — xem errors[] |
| 429 | test_quota_exceeded | Hết hạn mức Sandbox |
| 429 | rate_limited, tenant_rate_limited | Quá số lượt/phút của khoá hoặc tenant |
| 429 | quota_exceeded | Người dùng cuối hết hạn mức gói |
Voicebox
| HTTP | code | Nguyên nhân → cách xử lý |
|---|---|---|
| 403 | origin_not_allowed | Trang chưa có trong danh sách origin được phép |
| 403 | origin_required | App native gọi không có Origin ⇒ cần bật Cho phép app native |
| 403 | voicebox_disabled | Voicebox đang tắt |
| 401 | token_required, token_invalid, token_expired | Lấy token phiên mới (widget tự làm) |
| 401 | identity_required, identity_invalid | Thiếu/sai user.hash |
| 401 | screen_context_invalid | Thiếu/sai chữ ký tham số signed |
| 422 | input_too_long, audio_too_long | Vượt giới hạn ký tự / giây âm thanh |
| 422 | screen_context_required, screen_context_invalid_value, screen_context_too_large | Sai tham số trang |
| 429 | rate_limited | Gửi quá nhanh — đọc Retry-After |
| 503 | voicebox_not_provisioned | Voicebox mất API key nội bộ — liên hệ hỗ trợ |
| 503 | core_unreachable, config_unavailable | Hệ thống bảo trì — widget tự hiện câu dự phòng và nút "Thử lại" |
Giới hạn lưu lượng
- Mọi phản hồi
429có headerRetry-After(giây) — chờ đúng thời gian rồi thử lại, không thử lại dồn dập. - Sandbox: 60 lượt/phút, 2.000 lượt/ngày mỗi tenant.
- Production: trần lượt/phút theo khoá và theo tenant, cấu hình theo thoả thuận.
Khi AI gặp sự cố
Aivigo tự chuyển sang nhà cung cấp AI dự phòng. Nếu vẫn không được, lượt trả lời bằng câu mẫu với degraded: true —
hiển thị bình thường, không cần xử lý đặc biệt.