EN ▾
Get API key

cursorapikey.com/Guide

Cursor API Keys Not Working: Custom Endpoint Fixes

When Cursor API keys are not working, the cause is almost always one of four things: the base URL, the model name, the key itself, or a limit on the account. A single curl command tells you which one.

Updated

Abstract code editor panel with a glowing key being inserted, a wrench and magnifier beside it
Isometric fork with paths to an editor, a server and a terminal, illustrating choosing an alternative to Cursor

Key points

  • Test the key outside Cursor first with curl; if curl works, the problem is in the Cursor settings.
  • Base URL must be https://api.cursorapikey.com/v1 and the model name must be exactly uncensored.
  • 401 means a bad key, 404 a bad URL, 429 a rate or concurrency limit, and a model error a wrong name.
  • Menu labels change between Cursor versions, so match the field purpose rather than the exact wording.

Step 1: test the key outside Cursor

Take Cursor out of the picture. If a plain request works, your key and account are fine and the fault is in the editor settings. If it fails, the error body names the problem.

curl -i https://api.cursorapikey.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with the word ready."}]}'

The -i flag prints the status line and headers. A 200 status with a choices array means success. The X-Balance-USD header shows your remaining credit, which is the first thing to check if you get an authorization or payment error.

You can also list models, which confirms the key without spending anything:

curl https://api.cursorapikey.com/v1/models -H "Authorization: Bearer YOUR_KEY" | grep uncensored

The response should contain the model ID uncensored.

Step 2: set the fields in Cursor

Open Cursor's settings and find the Models section. You need three values, and a mistake in any of them produces a failure that looks like a broken key.

  1. OpenAI API key: paste your key with no spaces or line breaks at either end.
  2. Override OpenAI base URL: turn the override on and enter https://api.cursorapikey.com/v1. Keep the /v1 and leave off /chat/completions.
  3. Custom model: add a model named uncensored and enable it. Disable models you do not use so Cursor does not select one the endpoint does not know.

After saving, use the verify option if your version has one, then pick uncensored in the chat model dropdown. A fresh chat tab is a good test, since an old tab may keep the model it started with. The step-by-step walkthrough in how to use the Cursor API shows the same setup with more context.

Match the error to the fix

What you seeLikely causeFix
401, "invalid key", "unauthorized"Key mistyped, truncated, or revokedCopy it again from the key page; check for trailing spaces
404, "not found"Wrong URL, missing /v1, or a doubled pathUse exactly https://api.cursorapikey.com/v1
"model not found" or similarModel name differs from uncensoredAdd the custom model with that exact name, lowercase
429 with rate_limitedOver the requests-per-minute limitSlow down; trial keys allow 60 per minute, full keys 300
429 with concurrencyToo many requests at onceReduce parallel agent runs; trial 2, full key 8
429 with Retry-After: 5Temporary overloadWait five seconds and retry
Works in curl, fails in CursorSetting not saved, wrong tab model, or feature that does not use custom keysSee the next section

Failed or refused requests are not charged, so retrying while you debug costs nothing.

When curl works but Cursor still fails

This is the most confusing case, and it has a few usual explanations.

The wrong model is selected. Cursor keeps its own built-in models in the list. If one of them is selected, the request does not go to your endpoint at all. Select uncensored explicitly in the dropdown of the chat or composer you are using.

Not every feature uses your key. Features that rely on Cursor's own models, such as inline autocomplete, may keep using them regardless of the key you add. Custom keys apply where you can pick the model, which is chat and edit modes. Check Cursor's current documentation, since this changes between releases.

Concurrency from agent mode. Agent and multi-step runs can fire several requests at once. A trial key allows two at the same time. If errors appear only in agent mode, you are likely hitting the concurrency limit, and a full key raises it to eight. A streamed request holds its slot until the stream ends, so long outputs occupy slots longer.

Tool calls. The API supports tool calling, with tool_calls streamed and results passed back as role: "tool". Quality of tool use depends on the model, so if an agent run stalls on a tool step, try the same task in plain chat first.

Check the account side

If curl returns an error about balance, the key is valid but the credit is empty or the trial has ended. The trial is $0.50, valid for 7 days, claimed with one click on the API key page after sign-up. After that you need a top-up.

Top-ups are any whole amount from $20 to $500, with +5% from $50, +10% from $100 and +15% from $200. You can pay by crypto (USDT on TRC20, USDC on Base). The pricing page shows the table. If you have no key yet, get one here.

Keep one key per tool. If you pasted a key into several editors and scripts, rate limits are shared across them, which can look like random failures.

Script check for a stubborn case

If you still cannot find the cause, run a short script that mirrors what the editor does. It uses the OpenAI SDK, which Cursor-style clients are modeled on, and it prints the exact error object.

from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.cursorapikey.com/v1", api_key="YOUR_KEY")

try:
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Write a one-line Python hello world."}],
        stream=True,
    )
    for chunk in r:
        print(chunk.choices[0].delta.content or "", end="")
except APIStatusError as e:
    print(e.status_code, e.response.headers.get("X-Request-Id"))
    print(e.response.text)

If the script streams text, the endpoint, key and model are correct, and the remaining issue is a Cursor setting. If it prints a status code, use the table above. Keep the X-Request-Id value when you contact support, since it identifies the exact request. Full parameter details are on the documentation page.

Keep it from breaking again

A few habits prevent most repeat problems. Store the key in one password manager entry and copy from there, rather than from chat logs or notes where line breaks sneak in. Write down the three values (base URL, key, model name) so you can re-enter them after an editor update, since updates sometimes reset overrides. After each update, send one short chat message before starting real work.

Watch the balance. The X-Balance-USD header is returned on each response, and you can also read it from GET /v1/balance. Credit never expires, so a modest top-up sitting in the account is not wasted. If you use the key from scripts as well as from the editor, give long batch jobs a retry loop that waits five seconds on a 429 and stops after a few attempts, so a script cannot starve your editor of its concurrency slots.

A coding chat request with 10,000 tokens of file context and a 700-token answer costs 10,000 / 1,000,000 x $0.15 = $0.0015 for input and 700 / 1,000,000 x $0.50 = $0.00035 for output, about $0.00185 in total. Rates are $0.15 per 1M input and $0.50 per 1M output tokens. The article on Cursor API pricing covers monthly estimates.

If the request that failed was a large one, remember the window: prompt plus completion must fit in 100,000 tokens, and the request body is capped at 8 MB. Attaching a whole repository to a chat can exceed both. Trim the context to the files that matter and try again.

01

Questions and answers

Why does Cursor say my API key is invalid?

Usually the key has a stray space or was copied partially, or the base URL still points at another service. Re-copy the key, then confirm the override URL is https://api.cursorapikey.com/v1.

Which model name do I enter?

Enter uncensored, in lowercase. It is the only model ID the API offers.

Does autocomplete use my key?

Not necessarily. Some Cursor features use Cursor's own models, and custom keys mainly apply to chat and edit modes where you choose the model.

Are failed requests billed?

No. Failed or refused requests are not charged, so retrying while you debug costs nothing.

Your key is one form away

Create an account, copy the key, change the base URL. That is the whole setup.