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ệ NextX nếu cần cấp lại secret
`401 oauth2.client_suspended`	App đã bị NextX đình chỉ	Liên hệ hỗ trợ NextX
`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

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": "crm.contacts.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.