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 explains both.
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.
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
Your credential reads the item's type but can't write it. details.grant names the grant it lacks:
{
"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.
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 lists the operations that need a recent sign-in.
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 gives the limit and how to lift the lock. Behind a proxy, every client can share one address, as The address explains.
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
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
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 lists the RATE_LIMIT_* limits.
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 changes the wait.