Lỗi
Hình lỗi {code, message} và toàn bộ mã lỗi public.
Mọi lỗi 4xx/5xx trên các endpoint public (/v2/token, /v2/agents,
/v2/conversations, /v2/chat, /v2/runs) đều có cùng một hình:
{ "code": "invalid_token", "message": "Authentication failed" }Lập trình theo code (dành cho máy đọc), không theo message (dành cho
người đọc — có thể thay đổi). Một số lỗi có thêm scope (ví dụ
budget_exceeded, queue_full) hoặc retry_after (ví dụ rate_limited, queue_full).
Mã lỗi
| Code | HTTP | Ý nghĩa |
|---|---|---|
invalid_token | 401 | Token hết hạn hoặc không hợp lệ. |
token_expired | 401 | Token đã hết hạn — đổi token mới. |
invalid_publishable_key | 401 | Publishable key không tồn tại hoặc bị thu hồi. |
origin_not_allowed | 403 | Origin của trang gọi không nằm trong danh sách cho phép. |
invalid_user_hash | 401 | Chữ ký user-hash không khớp identity secret. |
user_hash_expired | 401 | expires-at đã qua — tạo lại chữ ký mới. |
org_suspended | 403 | Tổ chức đang bị tạm ngưng. |
end_user_blocked | 403 | End-user này đã bị chặn. |
agent_not_found | 404 | Không tìm thấy agent. |
agent_inactive | 409 | Agent đang bị tắt (deactivate). |
conversation_not_found | 404 | Không tìm thấy cuộc hội thoại. |
run_not_found | 404 | Không tìm thấy run. |
run_not_cancellable | 409 | Run đã kết thúc, không thể huỷ. |
approval_pending | 409 | Cuộc hội thoại đang có một hành động chờ xác nhận — xác nhận hoặc từ chối trước khi gửi tin mới. |
run_not_waiting | 409 | Run này không chờ xác nhận (đã quyết định, đã kết thúc, hoặc chưa từng dừng). |
rate_limited | 429 | Vượt quá giới hạn tần suất — xem retry_after. |
budget_exceeded | 429 | Đã dùng hết ngân sách token trong ngày — xem scope. |
queue_full | 429 | Trợ lý đang quá tải — thử lại sau retry_after giây; xem scope (org hoặc deployment). |
validation_error | 422 | Nội dung request không hợp lệ. |
redis_unavailable | 503 | Streaming tạm thời không khả dụng — thử lại. |
internal_error | 500 | Lỗi phía Harnix — thử lại, hoặc liên hệ hỗ trợ nếu lặp lại. |
Đây là danh sách đóng — không có mã nào khác xuất hiện trên các endpoint public.