← Errors, limits and exit codes
What do access refusals mean?
Short answer
GilbPlatform answers 401 when it cannot tell who is asking, 403 when the caller may not act, and 404 when nothing readable is there.
Deeper
An access refusal is GilbPlatform's answer when a request may not do what it asks. Its body has error and message; the token address, POST https://id.gilb.com/base/oauth/token, answers with error and error_description instead.
401: GilbPlatform cannot tell who is asking. A call with no token where one is needed, such as a grant or a copy of a vault, answers This surface requires an authenticated caller (no token presented); a token that is not valid or has run out, and a DPoP proof that does not fit the request, answer 401 too. A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449).
404: a read of a record you may not read answers 404, the same as a record that does not exist, on purpose, so no one learns what is there. An access list asked for by someone without Control answers 404 not found the same way.
403: a change you may not make is refused openly, though with no token a change can answer 404 instead: a write without a write grant, vault target denied on a vault you may not reach, and a grant by someone who does not hold Control on the vault, whose message on most grant calls says the caller does not hold acl:Control. A grant to a named person, group or vault sent with a computer key, one added with gilb-computer add, answers 403 and says to do it in GilbApp.
For an app's server: the token call answers 401 invalid_client when the signed assertion, the short JWT your server signs with its key, is wrong, expired or used twice, and 400 invalid_scope for a scope other than base.read or base.write. An app that is not bound or not granted gets 404 on a read, the same as a missing record, and 403 on a write; a base.read token gets 403 on a write too.
Binding an app to its AI vault, a small vault that stands for an app or an AI, answers 400 client has no machine principal yet when the app's token was never used: use it once, then bind again. A bind by anyone but the person who made the AI vault, by a computer key or by the app itself, answers 403. No one can be given access into an AI vault: 400 reach-into-ai-agent-vault.
409 on a grant means another grant on the same record came at the same moment, and nothing changed: send it again. 503 means GilbPlatform could not read what it needed to decide, such as whether the caller holds the vault; nothing was decided, and the request can be sent again.
Most of these answers are in the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.Errors, https://appbuilder.gilb.com/base/e/06gkzpwxmnxf90zcc3mzc757xg, and Dev.Guide.AppAccess, https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec. It can be read with no sign-in, as data for programs and AIs rather than as a web page. The answer on why a result is empty helps when a read comes back with nothing. Not checked on production: the 409, the 503, the refusals for a computer key and for a bind by someone else, and reach-into-ai-agent-vault; they are from GilbPlatform's code.
Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/server/app.ts:244-256 (4xx body {error, message}); src/routes/machine-token.ts:10, :163-205 (token route: error, error_description, :203); src/auth/errors.ts:19-60 (Unauthorized 401, Forbidden 403, BadRequest 400); src/routes/consent.ts:96-98, :128-131 (404 {error:not found}); src/routes/authz.ts:645-700 (403 does not hold acl:Control, :696), :737-750 (409 ConcurrentWrite: nothing was changed by this request); src/auth/app-standing.ts:231-245 (computer refusal, do this in GilbApp); src/auth/owner-account-resolver.ts:190-203 (503 VaultHolderUnanswerable: neither applied nor denied on the merits); src/routes/read.ts:250-265 (identical 404 for missing and unauthorized); src/auth/bind-agent-vault.ts:110, :127 (client has no machine principal yet); src/authz/vault-access-edge.ts:1037-1041 (reach-into-ai-agent-vault). Dev.Guide.Errors (A 06gkzpwxmnxf90zcc3mzc757xg, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Answer13, Answer17, Answer21, Answer22, Answer23, Answer34, Answer35, Answer39, Answer40 (verified 2026-10-27), Answer41 (verified 2026-10-27). Dev.Guide.AppAccess (A 06gqw6jdn9sgbc9rfbfrwc7rec, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) FirstToken, Bind, Grant, Read, Write.: src/routes/authz.ts:696 (does not hold acl:Control: vault, group, scope and reach grants) and :483-493 (grant-direct and grant-write-direct: neither holds the vault of <record> nor holds acl:Control on it).: the 409 (authz.ts:737-750), 503 (owner-account-resolver.ts:190-203), computer-key 403 (app-standing.ts:231-245), bind-by-someone-else 403 (bind-agent-vault.ts:100-105) and reach-into-ai-agent-vault (vault-access-edge.ts) are read in code only, not in a Guide chapter or a production probe. Row: Developer.AppAccessRefusals.
Checked against GilbApp d529620.