Auth API Troubleshooting: Common Errors and How to Fix Them
When a key system "just stops working" for one user but runs fine for everyone else, the cause is almost always a small, identifiable mismatch rather than a broken server. This guide walks through the auth errors that surface most often during Panda Key System integrations and gives you a repeatable way to pin each one down.
Start With a Systematic Checklist
Most integration bugs are diagnosed faster by ruling things out in order than by guessing. Before you change any code, capture the exact error string the loader or validation endpoint returned, the affected user’s HWID, and whether the failure is universal or isolated to one executor. An error that hits every user points at configuration or deployment; an error that hits one user points at that user’s environment.
Work through this checklist in sequence: (1) confirm the key exists and is not expired or revoked in the dashboard; (2) confirm the HWID on the request matches the HWID bound to the key; (3) confirm the client is hitting the correct service ID and endpoint; (4) check whether the executor connected over WSS or fell back to HTTP; (5) inspect the server clock and any signature/identity-pin errors; (6) look for rate-limit responses. Nine times out of ten the answer surfaces in the first three steps, and Discord webhook logs give you a timestamped trail to compare against.
Invalid or Expired Key, and HWID Mismatch
An "invalid key" response usually means one of three things: the key string was truncated or whitespace-padded in transit, the key was revoked from the dashboard, or it expired. Trim the key client-side before sending it and log the exact bytes you transmit. A trailing newline from a clipboard paste is a classic culprit. If the dashboard shows the key as active but validation still fails, you are almost certainly sending the wrong service ID alongside it.
HWID mismatch is the most common per-user failure. It happens when a user resets their machine, switches executors (which can change how the hardware ID is derived), or shares a key across devices. The HWID lock is doing its job here, so the fix is a deliberate one: reset the HWID binding for that key from the dashboard, or hand HWID resets to users through whatever cooldown policy you set. Do not loosen the lock globally to solve one support ticket. That just trades a support load for a sharing problem.
Signature and Identity-Pin Mismatches
The V5 (Jellybean) client pins the server’s long-term Ed25519 identity, and Wilkins V4.5 signs its handshake too. A signature or identity-pin mismatch means the public key baked into the client does not match the private key the server is signing with. The number-one cause is shipping a client built against an old or regenerated key pair: if you rotate the server identity, every strict client must be rebuilt and redistributed before that rotation goes live.
When you see pin failures right after a deploy, verify the server is loading the private key you think it is (the canonical host and key env vars must match the build) and that the DLL or Lua client was actually rebuilt against the current public key. A stale client artifact is far more common than a genuinely malicious redirect, but the pin can’t tell the difference, and that strictness is the entire point. Treat a clear, diagnosable identity error as a build-pipeline reminder, not a bug to patch around.
WSS Fallback, Rate Limits, and Clock Skew
Some executors block LAN/private IPs or plain HTTP, and others have flaky WebSocket support, so a "no hello" or silent hang often means the WSS handshake never completed. Clients like V4.3-Cookies exist specifically as an HTTP fallback for these environments, and reinforced loaders auto-fall-back from WSS to HTTP after repeated failures. If one user can’t connect at all, confirm which transport their executor actually used before blaming the server.
Rate limiting shows up as a sudden burst of rejections from a single HWID or IP, frequently a retry loop hammering the validation endpoint. Add backoff between attempts and respect any retry-after hint instead of looping immediately. Clock skew is the quiet one: signed handshakes embed a timestamp, so a device whose clock is off by minutes will produce a valid signature that the server rejects as stale. If a single user fails identity checks while everyone else passes, have them sync their system clock before you touch anything else.
Executor Crypto Quirks
A subtle class of failures comes from executor crypto implementations that don't behave like a reference one. Some executors expose fast-path hashing or HMAC functions that truncate binary input at the first null byte. These pass naive ASCII self-tests but silently corrupt signatures on hex-keyed inputs, producing a server-side "signature mismatch" that looks impossible because the client code looks correct.
The safe response is to use the pure, manual crypto implementation shipped in the client library rather than swapping in an executor’s native fast paths. If you are debugging a signature error that only appears on certain executors and the same key works elsewhere, suspect the crypto primitive before the auth logic. Run a known-answer test against a non-trivial binary input to confirm the executor’s hash matches the expected output.
Key takeaways
- Capture the exact error string, HWID, and transport (WSS vs HTTP) before changing code. Most failures are diagnosed by ruling things out in order.
- Invalid-key and HWID-mismatch issues are usually whitespace, wrong service ID, or a legitimately moved/shared device; reset the binding deliberately rather than loosening the lock.
- Identity-pin and signature failures after a deploy almost always mean a stale client artifact or mismatched server key, not an attack.
- WSS hangs, rate-limit bursts, and clock skew each have distinct signatures. Check transport, add backoff, and verify the user’s system clock on signed handshakes.
- Signature errors that only hit certain executors point at crypto quirks; use the library's reference implementation and validate with a known-answer test.