Error code
Lỗi trả về theo chuẩn problem+json (RFC 9457). Lỗi do cổng API sinh ra có thêm header X-Error-Source: gateway.
Thân lỗi
401
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
X-Error-Source: gateway
{
"type": "https://nextx.vn/errors/unauthorized",
"title": "Vui lòng đăng nhập để tiếp tục.",
"status": 401,
"traceId": "0HN7…",
"errorCode": "gateway.unauthorized",
"retryable": false
}errorCode ổn định để máy đọc; title là câu cho người đọc; retryable cho biết gọi lại có thể thành công; gửi kèm traceId khi nhờ hỗ trợ.
Bảng mã HTTP
| HTTP | Ý nghĩa | Xử lý |
|---|---|---|
400 oauth2.missing_client_id | Thiếu client_id khi lấy token (tương tự oauth2.missing_client_secret, oauth2.missing_workspace_id) | Gửi đủ client_id, client_secret, workspace_id dạng form |
400 oauth2.unsupported_grant_type | grant_type không hỗ trợ | Dùng grant_type=client_credentials |
401 oauth2.invalid_client | Sai client_id / client_secret, hoặc client không phải loại confidential | Kiểm tra lại cặp khoá; liên hệ Gym Master nếu cần cấp lại secret |
401 oauth2.client_suspended | App đã bị Gym Master đình chỉ | Liên hệ hỗ trợ Gym Master |
403 oauth2.app_not_installed | Workspace chưa cài app (chưa consent) — KHÔNG phải 404 | Workspace vào Ứng dụng kết nối để cài app và đồng ý scope |
403 oauth2.module_not_subscribed | Sau khi lọc theo phân hệ workspace đang mua, không còn scope nào | Xin scope thuộc phân hệ workspace đã mua, hoặc mua thêm phân hệ |
401 gateway.unauthorized | Bearer token / API key thiếu, hết hạn hoặc sai (problem+json, errorCode gateway.unauthorized) | Lấy token mới (TTL 3600s, phản hồi có refresh_token nhưng rỗng) |
403 insufficient_scope | Chỉ ở ~25 route trong bản đồ scope của gateway: body { error: insufficient_scope, required: <scope> } | Xin thêm scope trong required + workspace consent |
403 Permission required: <scope> | Route còn lại do service kiểm: thiếu scope trả 403 với detail "Permission required: <scope>" | Xin thêm scope nêu trong detail |
404 | Tài nguyên không tồn tại | Kiểm tra id / đường dẫn |
429 | Vượt rate-limit (mặc định 600 req/phút mỗi app) | Giãn nhịp gọi, đọc header Retry-After |
Error code của API tổng đài
Đọc errorCode để xử lý theo từng trường hợp; title là câu cho người xem.
| errorCode | HTTP | Ý nghĩa |
|---|---|---|
call.partner.agent_ref_required | 422 | Gửi đúng một trong agentId / agentEmail / extension. |
call.agent.not_found | 404 | Không có tổng đài viên này trong workspace (hoặc đã tắt). |
call.partner.agent_not_allowed_for_key | 403 | API key đã bị khoanh, không gọi thay được tổng đài viên này. |
call.agent.not_available | 409 | Tổng đài viên đang bận / tạm nghỉ / ngoại tuyến. |
call.partner.number_invalid | 422 | Số điện thoại không chuẩn hoá được về E.164. |
call.outbound.number_blocked | 409 | Số nằm trong danh sách không gọi (DND). |
call.partner.caller_id_not_owned | 422 | callerId không phải số của workspace. |
call.partner.transfer_target_required | 422 | Gửi đúng một đích chuyển máy. |
call.partner.call_not_active | 409 | Cuộc gọi đã kết thúc. |
call.partner.recording_not_available | 404 | Cuộc gọi chưa có ghi âm. |
call.esl.unavailable | 502 | Tổng đài tạm không nhận lệnh — retry sau vài giây. |
Thiếu quyền (403)
Tuyến do cổng kiểm trả error: insufficient_scope kèm required (quyền cần). Tuyến do phân hệ kiểm trả detail dạng Permission required: <scope>.
403
{ "error": "insufficient_scope", "required": "gym.members.view" }Khi nào nên gọi lại
Chỉ gọi lại khi retryable: true (429, 502, 503, 504), giãn cách tăng dần. Lệnh ghi gửi kèm Idempotency-Key để gọi lại không tạo bản ghi trùng.