# Credentials and access (/run/troubleshooting/credentials-and-access)

Fix a key Marfa refuses, a sign-in that fails, and a request refused for its reach or its rate.



Marfa checks every request's credential, then what that credential may reach. [Access](/access) explains both.

## 401 unauthorized [#401-unauthorized]

Marfa didn't accept the credential: it's missing, mistyped, revoked or expired. The CLI exits with `5`.

Send it in full, as `Authorization: Bearer <key>`. If Marfa still refuses it, the key was revoked or has expired: [make a new one](/run/manage-keys#make-a-key).

## 404 item_not_found for an item you know exists [#404-item_not_found-for-an-item-you-know-exists]

Your credential can't read the item's type. Marfa answers as it does for a missing item, so a refusal never reveals what a credential can't see.

Check which types the credential reads with `marfa overview`, or the whole map of a key with `marfa keys current`, then use a key that reads the type. The overview never lists `system.*` types and caps how many it lists. If the answer carries `"details": { "trashed": true }`, the item is in the bin: restore it before you change it.

## 403 type_not_permitted [#403-type_not_permitted]

Your credential reads the item's type but can't write it. `details.grant` names the grant it lacks:

```json
{
  "error": {
    "code": "type_not_permitted",
    "message": "Write access to type \"core.note\" denied",
    "details": { "grant": { "kind": "type", "name": "core.note", "level": "write" } }
  }
}
```

Use a key that holds the grant, or [make one](/run/manage-keys#make-a-key).

## 403 forbidden: Sign in again to perform this operation [#403-forbidden-sign-in-again-to-perform-this-operation]

The operation, such as making or revoking a key, needs a sign-in from the last five minutes. Marfa changes nothing. The owner's console asks you to confirm it's you first, so you meet this message from a program, or after a confirmation you refused.

Sign in again in a browser, or use the private socket. A key can't confirm. [Confirm it's you](/run/sign-in-as-the-owner#confirm-its-you) lists the operations that need a recent sign-in.

## Too many sign-in attempts (too_many_attempts) [#too-many-sign-in-attempts-too_many_attempts]

The owner's password was tried too often, and Marfa answers `429` with `Retry-After`. The sign-in page says how many minutes to wait, and that a passkey still signs in.

Wait, or sign in with a passkey. [Recover the owner's password](/run/sign-in-as-the-owner#recover-the-owners-password) gives the limit and how to lift the lock. Behind a proxy, every client can share one address, as [The address](/run/deploy#the-address) explains.

## Owner setup and sign-in require HTTPS, except on loopback development hosts [#owner-setup-and-sign-in-require-https-except-on-loopback-development-hosts]

`MARFA_AUTH_BASE_URL` is a plain `http` address that isn't `localhost`, so the server refuses the owner's pages and passkeys with `403 forbidden`.

Serve the instance over `https`, and set `MARFA_AUTH_BASE_URL` to that address. A passkey belongs to its host name, so sign in at the same address each time.

## That code wasn't recognized [#that-code-wasnt-recognized]

A code from `marfa login` works once, for 10 minutes. The device page words an expired code this way.

Run `marfa login` again, and approve the new code within 10 minutes.

## 429 rate_limited [#429-rate_limited]

The credential sent more requests in the current window than the instance allows. The CLI exits with `3`, which means a retry can succeed.

Wait the seconds `Retry-After` names, then send the request again. [Settings](/run/settings) lists the `RATE_LIMIT_*` limits.

## 408 request_timeout on a restore or an upload [#408-request_timeout-on-a-restore-or-an-upload]

No bytes of a restore or a file upload arrived for 60 seconds, so the server ended it and wrote nothing.

Send the request again over a connection that stays up. `MARFA_UPLOAD_IDLE_TIMEOUT_MS` in [Settings](/run/settings#every-environment-setting) changes the wait.