How can I distinguish an authentication problem from a permissions problem?

Question

When an external tool cannot read a Busabase record, what should I check first to determine whether its credentials are invalid, its access is insufficient, or the requested record does not exist? Which response details are useful for troubleshooting without repeatedly replacing credentials?

Kelly · Answer

Thanks for asking. When an external tool cannot read a [Busabase](https://busabase.com) record, **read the HTTP status and error code first** — do not rotate the API key on every failure. Auth problems, permission problems, and “missing record” look different.

![](https://s1.busabase.com/attachments/cHEfVIklx0ASY7gZ6iJhU7wCONhhfJNb/blobs/sha256/a7/a74d96ddd02277caa00d6d0a7e13dd4c1b41a10d6acd94b208b5f1b3f67ae152.png)

*Diagram · API error triage*

## What each outcome usually means

| Response | Likely cause | What to do |
|----------|--------------|------------|
| **401 Unauthorized** | Key invalid, expired, deleted, or the owner account is suspended | Fix or recreate the key; check expiry in Space settings → API keys |
| **403 Forbidden** | Key is accepted, but its **permission level** is too low for the call, or the key’s owner has no access to that Space / resource | Raise the key level, grant Space access, or use a key that already can read there |
| **404 Not found** | Credentials work, but this Base / record id is wrong or not in the Space you are calling | Confirm Space, Base, and record id; try a known-good list/read first |

Official matrix: [API keys](https://busabase.com/docs/api-keys).

## Practical troubleshooting order

1. Capture **status + `code` / message** from the response body (log them; do not only screenshot the client UI).
2. With the **same key**, call a cheap known-good read (for example list Bases you expect to see).  
   - If that already returns 401 → stop and fix credentials.  
   - If that works but the target record returns 403 → permissions / membership, not “bad key”.  
   - If that works but the target returns 404 → identity / wrong Space, not credentials.
3. Only replace the key when you have a clear 401 (or you know the old key was revoked).

## Boundaries

- A **read**-level key can authenticate and still get **403** on write/merge — that is expected, not a broken key.
- “Record does not exist” and “you may not see it” can both feel empty in a UI; trust the status code, not only the empty screen.
- Avoid embedding keys in shared logs; log status/code only.

If you paste one anonymized status + code (no key), we can narrow which of the three branches you are on.

Response	Likely cause	What to do
401 Unauthorized	Key invalid, expired, deleted, or the owner account is suspended	Fix or recreate the key; check expiry in Space settings → API keys
403 Forbidden	Key is accepted, but its permission level is too low for the call, or the key’s owner has no access to that Space / resource	Raise the key level, grant Space access, or use a key that already can read there
404 Not found	Credentials work, but this Base / record id is wrong or not in the Space you are calling	Confirm Space, Base, and record id; try a known-good list/read first

What each outcome usually means

Practical troubleshooting order

Boundaries

Your reply