Từ điển mã lỗi
Các mã lỗi có thể gặp khi tích hợp, nguyên nhân và cách khắc phục.
Đây là các mã lỗi thường gặp khi tích hợp, nguyên nhân và cách khắc phục. Lỗi trả về trình duyệt nằm trong chuỗi truy vấn (query string) của callback URL, còn lỗi của token và API nằm trong nội dung JSON.
Yêu cầu ủy quyền GET /oauth/authorize
| Mã | Nguyên nhân | Cách khắc phục |
|---|---|---|
unsupported_response_type | response_type không phải code | Hãy cố định response_type=code. Không hỗ trợ giá trị khác |
invalid_request | Một trong client_id, redirect_uri, state bị để trống | Cả ba đều bắt buộc. Lỗi phổ biến nhất là quên state |
pkce_required | Thiếu code_challenge | PKCE là bắt buộc, không phải tùy chọn. Xem Bước 5 của Tích hợp trong 5 phút |
invalid_code_challenge_method | code_challenge_method không phải S256 | Chỉ chấp nhận S256. Không hỗ trợ plain |
unauthorized_client | Không có client ứng với client_id | Hãy kiểm tra bạn đã sao chép nguyên giá trị trong Tài khoản của tôi chưa |
invalid_scope | Scope để trống hoặc nằm ngoài danh sách cho phép | Chỉ dùng được các scope trong Tra cứu scope |
insufficient_scope | Yêu cầu scope chưa được cấp cho dịch vụ này | service.domain.read cần quản trị viên cấp |
access_denied | Dịch vụ hoặc client không ở trạng thái hoạt động — chưa xác minh tên miền, chưa đăng ký callback, hoặc đã bị chặn | Hãy kiểm tra trạng thái dịch vụ trong Tài khoản của tôi. Trạng thái phải là «Đang hoạt động» |
invalid_redirect_uri | redirect_uri khác với callback đã đăng ký | Phải khớp chính xác từng ký tự. Hãy kiểm tra cả dấu gạch chéo cuối, http/https và cổng (port) |
Đổi token POST /oauth/token
| Mã | HTTP | Nguyên nhân · Cách khắc phục |
|---|---|---|
unsupported_grant_type | 400 | grant_type chỉ chấp nhận authorization_code hoặc refresh_token |
invalid_request | 400 | Thiếu tham số bắt buộc. Hãy kiểm tra có quên code_verifier không |
invalid_client | 401 | client_id/client_secret không khớp. Hãy thử sao chép lại secret |
invalid_grant | 400 | Code đã được dùng, đã quá 10 phút hoặc không tồn tại. Code chỉ dùng một lần |
invalid_grant+ pkce verification failed | 400 | code_verifier không khớp với code_challenge đã dùng khi yêu cầu ủy quyền. Hãy kiểm tra bạn đang gửi đúng nguyên giá trị đã lưu trong phiên |
invalid_redirect_uri | 400 | redirect_uri trong yêu cầu token khác với lúc yêu cầu ủy quyền. Cả hai lần phải gửi cùng một giá trị |
server_error | 500 | Lỗi nội bộ máy chủ. Nếu lặp lại, vui lòng liên hệ với chúng tôi |
Thông tin người dùng GET /oauth/userinfo · GET /oauth/domain-info
| Mã | HTTP | Nguyên nhân · Cách khắc phục |
|---|---|---|
invalid_token | 401 | Token bị thiếu, đã hết hạn (mặc định 1 giờ) hoặc đã bị thu hồi. Hãy dùng refresh_token để lấy token mới |
insufficient_scope | 403 | /oauth/domain-info cần có service.domain.read |
Các tình huống thường gặp
«Chắc chắn đúng rồi mà cứ báo invalid_redirect_uri»
Hầu hết là do dấu gạch chéo ở cuối. Nếu giá trị đã đăng ký là https://vi-du.com/oauth/callback
mà yêu cầu lại gửi https://vi-du.com/oauth/callback/, hệ thống coi đó là hai giá trị khác nhau.
Cách chắc chắn nhất là sao chép chuỗi đã đăng ký trong Tài khoản của tôi rồi dán vào.
«Đăng nhập được nhưng không nhận được email»
Nhiều khả năng không phải do scope. Email nằm trong profile.basic và được cung cấp mặc định, nhưng
có thể tắt theo từng dịch vụ. Hãy xem chính sách email trong Tra cứu scope.
«access_denied cứ liên tục xảy ra»
Hãy kiểm tra trạng thái của dịch vụ, không phải của client. Yêu cầu ủy quyền chỉ được chấp nhận khi đủ cả ba điều kiện: đã xác minh tên miền, đã đăng ký callback URL và trạng thái là «Đang hoạt động».