Lỗi Cursor khi dùng API key riêng: Invalid API key, Model name is not valid, 403 và cách sửa

Trước khi sửa: Cursor dùng key của bạn thế nào?

Nhiều lỗi biến mất khi nắm năm điểm sau về cách Cursor xử lý API key riêng (BYOK):

• Cần gói đủ quyền: từ khi có The X Subscription (12/10/2026), key riêng chỉ dùng được từ gói Premium trở lên, ở các gói cũ Pro, Pro+, Ultra và ở Teams, Enterprise. Gói Free và Plus bị chặn ngay trên máy chủ của Cursor.
• Năm nhà cung cấp được hỗ trợ chính thức: OpenAI, Anthropic, Google, Azure OpenAI và AWS Bedrock. Dịch vụ khác đi qua ô Override OpenAI Base URL; nhân viên Cursor khẳng định đây là cách cấu hình được hỗ trợ, nhưng không cam kết mọi nhà cung cấp ngoài danh sách đều chạy ổn định.
• Key riêng chỉ áp cho model chat (Agent, Chat, Ask, Edit). Tab, model riêng của Cursor như Composer, Grok và Cursor CLI không dùng key của bạn.
• Mọi request đi qua máy chủ của Cursor để dựng prompt rồi mới tới nhà cung cấp, nên endpoint phải là địa chỉ HTTPS truy cập được từ Internet; chính sách Zero Data Retention của Cursor không áp cho request dùng key riêng.
• Từ bản 3.20 (10/09/2026), mỗi nhà cung cấp có ô key riêng và công tắc “Use … API Key” hiện ra sau khi lưu key; key tự lưu khi rời ô hoặc nhấn Enter, ô key chỉ hiện chữ “Secret saved”, không có nút Save riêng.

Invalid API key. Unauthorized User API key

Thông báo này (mã ERROR_BAD_USER_API_KEY) nghĩa là nhà cung cấp đã trả lỗi 401 cho key Cursor gửi đi. Nguyên nhân hay gặp: key cũ hoặc gõ sai; ô Override OpenAI Base URL còn bật từ lần cấu hình trước; ô base URL vẫn để giá trị mặc định https://api.openai.com/v1 trong khi key là của nhà cung cấp khác, nên OpenAI từ chối key đó.

Cách sửa: dán lại key, kiểm ô base URL. Lưu ý mỗi lần tắt rồi bật lại công tắc Override, Cursor điền lại giá trị mặc định của OpenAI, nên phải dán lại địa chỉ của bạn và nhấn Enter để lưu. Với key Anthropic, key phải tạo trong Claude Console (bắt đầu bằng sk-ant-); gói Claude Pro trên claude.ai không phải API key.

AI Model Not Found hoặc Model name is not valid

Lỗi này nghĩa là request tới máy chủ Cursor mà không kèm key của bạn, nên Cursor không biết model tuỳ chỉnh đó là gì. Nguyên nhân hay gặp:

• Công tắc Use OpenAI API Key đang tắt. Sau đợt cập nhật tháng 10/2026, nhiều cấu hình cũ không tự bật công tắc mới này.
• Key chưa lưu được: dán xong chưa rời ô hay nhấn Enter.
• Tên model bắt đầu bằng claude-: Cursor đưa tên này sang ô key Anthropic, nên nếu bạn chỉ có key OpenAI hay key gateway, request đi mà không có key.

Cách sửa lỗi Model name is not valid

Làm lần lượt các bước, kiểm lại sau mỗi bước:

1. Dán lại key vào ô OpenAI API Key, nhấn Enter, rồi bật công tắc Use OpenAI API Key.
2. Bật Override OpenAI Base URL và kiểm địa chỉ; với STEYG Code là https://steyg.one/api/v1.
3. Đặt tên model tuỳ chỉnh không bắt đầu bằng claude- và khớp đúng model id của endpoint; với STEYG Code, dùng tiền tố steyg/ cộng model id.
4. Thoát hẳn Cursor rồi mở lại, mở một cuộc chat mới và chọn model vừa thêm.

This model does not support custom API keys

Bạn đang chọn một model do Cursor tự chạy, như Composer hay Grok, trong khi key OpenAI đang bật. Key OpenAI và ô Override áp cho mọi model không phải Claude hay Gemini, kể cả model của Cursor, mà các model này không chạy bằng key ngoài. Tắt công tắc Use OpenAI API Key khi muốn dùng Composer, Grok, hoặc chọn chế độ Auto (Auto không gửi key của bạn khi chuyển sang model của Cursor). Muốn dùng model GPT cài sẵn của Cursor cũng phải tắt Override, vì lúc Override bật, mọi request họ OpenAI đều đi tới địa chỉ của bạn.

Agent and edit rely on custom models that require a paid subscription

Tài khoản đang ở gói Free. Thông báo đầy đủ khuyên nâng lên gói trả phí hoặc tắt API Keys. Trong khoảng cuối năm 2025 đến đầu năm 2026, Cursor chuyển sang chặn key riêng của gói Free ngay trên máy chủ, nên hạ phiên bản ứng dụng cũng không lách được. Gói Plus mới cũng không dùng được key riêng hay model bên thứ ba như Claude; theo nhân viên Cursor, đây là giới hạn của gói chứ không phải lỗi của key. Trên gói Free, thông báo “You've hit your usage limit” dù đã nhập key cũng thường chỉ là bước kiểm gói này.

We're having trouble finding the resource you requested

Đây là lỗi 404 từ endpoint, Cursor hiện dưới dạng Provider Error. Nguyên nhân hay gặp: model id không có ở endpoint; gửi ảnh cho model không đọc được ảnh; tên model trùng một model Cursor tự chạy (ví dụ vài tên của Kimi) nên không đi theo ô Override; hoặc nhà cung cấp không được hỗ trợ, như xAI. Đối chiếu trường id trong GET /v1/models của endpoint và đổi sang tên không trùng model cài sẵn.

Khi dùng địa chỉ tuỳ chỉnh, Cursor chỉ gọi <base URL>/chat/completions, nên base URL phải kết thúc ở /v1; thiếu đoạn này thì đường dẫn cuối cùng sai.

Request failed with status code 403: Access to private networks is forbidden

Base URL đang trỏ vào localhost hoặc địa chỉ trong mạng nội bộ, ví dụ Ollama hay LM Studio chạy trên máy bạn. Vì request xuất phát từ máy chủ của Cursor, endpoint phải là địa chỉ HTTPS công khai; nhân viên Cursor gợi ý đưa server cục bộ ra ngoài qua đường hầm như ngrok hay Cloudflare Tunnel nếu bắt buộc. Cách chạy model cục bộ cho các công cụ khác có ở bài Ollama là gì.

User API Key Rate limit exceeded

Cursor chỉ chuyển lại lỗi 429 mà endpoint của bạn trả về, không phải giới hạn do Cursor đặt. Agent của Cursor gửi nhiều request trong thời gian ngắn, nên dễ chạm giới hạn số request mỗi phút hay số token mỗi phút của key. Chờ một lúc rồi thử lại, hoặc nâng giới hạn của key ở nhà cung cấp; ý nghĩa các mã lỗi chung có ở bài lỗi API thường gặp.

We're having trouble connecting to the model provider

Thông báo này có nhiều nguyên nhân: nhà cung cấp từ chối request (từ 23/10/2026, Cursor hiện câu rõ hơn là request bị chặn theo quy định sử dụng của nhà cung cấp), máy chủ Cursor không mở được kết nối tới endpoint, hoặc còn một công tắc key thừa đang bật, ví dụ Azure với ô URL trống. Cách xử lý theo nhân viên Cursor:

• Mở cuộc chat mới; tắt Override và các key không dùng tới.
• Tạm tắt MCP để loại trừ.
• Bật tuỳ chọn Disable HTTP/2 (chế độ HTTP 1.1) nếu mạng công ty hay proxy chặn HTTP/2.
• Kiểm số dư ở nhà cung cấp; key Anthropic hết tiền sẽ báo “Your credit balance is too low to access the Anthropic API”.
• Mở Help, Toggle Developer Tools, tab Network để xem mã lỗi và đường dẫn thật Cursor đã gọi.

Một ô Override cho mọi model, không có Override cho Anthropic

Override OpenAI Base URL là một địa chỉ dùng chung cho mọi model không phải Claude hay Gemini; chưa đặt riêng được cho từng model. Ô key Anthropic luôn gọi thẳng Anthropic và chưa có ô đổi base URL, nên muốn dùng model Claude qua một gateway, bạn phải đi đường OpenAI-compatible với tên model không bắt đầu bằng claude-. Khi dùng Override, tắt AWS Bedrock, vì bật Bedrock thì mọi request bị chuyển sang Bedrock. Cấu hình đầy đủ cho STEYG Code có ở bài Cursor, Cline dùng API key riêng.

Dùng key riêng có còn tốn tiền Cursor không?

Với gói cá nhân Premium, Super, Ultra và các gói cũ Pro, Pro+, Ultra: nhà cung cấp tính tiền model trực tiếp cho bạn, request dùng key riêng không trừ vào hạn mức hay credit trả trước của Cursor. Với Teams và Enterprise, Cursor vẫn thu một khoản phí theo token cho request dùng key riêng.

Lưu ý chi phí: theo một trả lời của nhân viên Cursor (10/2026), nếu model không trả output trong khoảng 3 phút, Cursor tự gửi lại toàn bộ hội thoại, nên một lượt treo có thể bị nhà cung cấp tính hai lần. Dòng “Errored, No Charge” trên trang usage của Cursor chỉ nói Cursor không tính phí, không nói nhà cung cấp không tính.

API key của Cursor khác API key của nhà cung cấp

Key bắt đầu bằng crsr_ tạo trong Dashboard của Cursor, mục API Keys, dùng cho Admin API, Cloud Agents API, Cursor CLI và SDK; tài liệu ghi rõ đây không phải API gọi model kiểu chat completions. Không có “API key Cursor miễn phí”: gói Free chỉ có Agent, Chat và Tab bằng model của Cursor với hạn mức nhỏ, ưu đãi học sinh đã dừng nhận đăng ký mới từ 25/06/2026 và chương trình giới thiệu đã kết thúc. Muốn có key gọi Claude, GPT để nhập vào Cursor, xem bài cách lấy API key OpenAI, Claude, Gemini.

Câu hỏi thường gặp