Perplexity API 401 Unauthorized

A 401 is the earliest possible refusal. The connection succeeded, TLS completed, the request reached Perplexity — and it was rejected before anything in the body was parsed. Your model id was never checked. Your parameters were never validated. Your usage was never consulted. Everything you would normally inspect when a call fails is downstream of the point at which this one stopped.

That is what makes it the fastest error in the catalogue to fix and the easiest to misdiagnose. Teams reach for the payload, the SDK version and the status page, when the entire fault surface is one string and how it travelled. The six causes below are ordered by how often they turn out to be the answer, and the first two account for most of them.

401, 403 and 429 are three different problems with three different owners

These get filed together as “the API rejected us” and handled by one branch in a client, which is how a credential problem ends up in a retry loop and a permission problem ends up in a secret rotation. The distinction is about which question the service refused to answer.

The row that costs the most time is the second one. A client that applies one retry policy to all 4xx responses will hammer a deterministic refusal until its deadline expires, turning an error that could have been surfaced in milliseconds into a request that hangs for the full retry budget. The throttling case is genuinely different and is covered in the Perplexity 429 guide.

Read the raw response, not the SDK exception

Most SDKs collapse an auth failure into a generic exception class and a message that has been through two layers of wrapping. The status code survives; the body, which is where the provider explains which of the six causes applies, frequently does not. Reproduce the call at the wire level before you form a theory:

curl -i -s -X POST https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sonar","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'

# Confirm the shell is holding what you think it is holding - never print the key:
echo "len=${#PERPLEXITY_API_KEY} prefix=${PERPLEXITY_API_KEY:0:4}"

That second line resolves more 401s than any amount of reading client code. It answers two questions at once: whether the variable is set at all in this context, and whether the value has an unexpected length — the signature of a trailing newline or a truncated copy-paste. Print the same two facts at application startup and the next occurrence is diagnosed from a boot log rather than a reproduction.

The Perplexity trap: the credential is fine and the balance is zero

Perplexity’s API is funded by a purchased credit balance rather than an invoice at the end of the month. That is a billing detail with an operational consequence most teams meet exactly once, at the worst time: when the balance is exhausted, requests stop being served, and the error reaching your client looks like an authentication problem rather than an accounting one. Engineers see an auth-shaped failure, assume the key was revoked, and start rotating — which issues a brand-new key against the same empty balance and fails identically.

What makes this specifically dangerous is the timing. A balance drains fastest under the traffic you most care about, so the failure arrives during your busiest hour and looks, from the shape of the graph, exactly like a provider incident: a clean cliff from full success to total failure with no ramp. Real credential problems tend to appear at deploys and rotations; a balance cliff appears at peak. Put the balance on a dashboard next to your error rate and the two become impossible to confuse.

The second Perplexity-specific cause is scope. Consumer Perplexity accounts and API access are not the same product, and a subscription to the former grants nothing to the latter. A team that has Perplexity Pro and assumes the API is included will generate a key-shaped string in the wrong place and be refused by api.perplexity.ai every time. Confirm the key came from the API console and begins with the pplx- prefix before you debug anything else.

The six causes, in the order worth checking

Work down this list rather than across it. Each step is cheap, and the ordering reflects which answers turn out to be correct most often rather than which are most interesting.

• The prepaid credit balance is exhausted. A valid key with no funds behind it. Rotation cannot fix it; only topping up can. Alert on the balance, not just on errors.
• The credential came from the consumer product, not the API console. A Pro subscription is not API access. Perplexity API keys carry the pplx- prefix and are issued in the API settings.
• The key was rotated and only some hosts got the new one. A partial rollout produces a 401 rate that is a clean fraction of traffic. That ratio is the diagnosis.
• Whitespace or a newline rode along with the secret. A key read from a file or piped through a shell frequently carries a trailing newline. The header becomes invalid and the value still looks perfect in a dashboard.
• The header was built by hand and lost the scheme. Perplexity expects Authorization: Bearer <key>. Sending the bare key is a 401 with a valid credential inside it.
• A proxy stripped or rewrote the Authorization header. Corporate egress proxies and some service meshes drop inbound auth headers by policy. The 401 you are reading was never emitted by Perplexity.

Notice what is absent from that list: anything about your request body, your model choice or your traffic volume. If you find yourself editing a prompt or lowering concurrency in response to a 401, you have left the fault surface entirely. The complete map of which code means what is in the Perplexity API error codes reference.

Make the next one impossible instead of fast

A 401 is a five-minute fix that recurs forever unless the conditions that produced it change. Three structural changes remove most of the category permanently, and none of them are about the key itself:

• Rotate with an overlap window. Issue, roll, verify from every environment, then revoke. An atomic rotation guarantees a failure window whose length is your deploy time. The sequence is in the Perplexity key rotation guide.
• Read the secret at request time, not at import time. A credential cached in a module-level constant at process start cannot be updated without a restart, which is why rotations turn into deploys and deploys turn into windows.
• Pass the key explicitly to every client. Ambient resolution from environment variables is convenient in a single-provider process and a liability in any process that talks to two, because the wrong credential is a valid one belonging to somebody else.
• Synthetically exercise every credential you hold. A key used only by a fallback path or a monthly batch job is a key you will discover is dead at the moment you need it. A one-request-per-hour probe per credential turns that into a Tuesday-morning ticket.
• Alert on auth failures separately from availability. A 401 rolled into a general error-rate alert either pages the wrong person or hides inside noise. It has its own owner and its own runbook, so it deserves its own signal. The setup is in the Perplexity status alerts guide.

Frequently Asked Questions

Related Perplexity Guides

• Perplexity API Key Setup Guide
• Perplexity API Key Rotation Guide
• Perplexity API Error Codes Reference
• Perplexity API 429 Too Many Requests
• Perplexity API 503 Service Unavailable
• Perplexity API Errors in the UI: what to show the user
• Is Perplexity Down? Outage Checking Guide