# Why was a vocabulary read refused?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

A refused vocabulary read changes nothing; its error names the cause: 400 for an option, 404 for a missing name, 409 for a clash.

## Deeper

A vocabulary read asks GilbVeda, the shared list of terms, at https://veda.gilb.com/base, for a term, a list, a search or a count of the apps that use a term. A term is the shared name GilbVeda keeps for a kind of thing, a detail of it, a link between two things, or a species. A refused read changes nothing. Its body has error and message, and some add details, such as the largest number allowed. Nothing is cut short or left out in silence: a read that cannot answer exactly what was asked is refused by name. The answers on [reading a term by name](http://support.gilb.com/help/how-do-i-read-a-term-by-name-and-the-json-ld-context) and on [listing, browsing and searching the vocabulary](http://support.gilb.com/help/how-do-i-list-browse-and-search-the-vocabulary) show each read. So does the answer on [recording which terms your app uses](http://support.gilb.com/help/how-do-i-record-which-terms-my-app-uses).

GET /base/vocab answers 400 "LimitMalformed" for a limit that is not a positive whole number, such as abc, 1.5 or -1, and "LimitOutOfRange" for a whole number outside 1 to 2000, such as 0 or 2001: a smaller page is never sent instead. "SelectorRepeated": limit, cursor or nodeKind sent twice; only type may repeat. "CursorMalformed": a cursor, the token that marks where the next page starts, not taken unchanged from the last page's next. "SelectorCombinationUnsupported": type together with nodeKind, limit or cursor. "NodeKindEmpty": nodeKind with no kind. "type\_token\_unresolved": a type written as t:Note or as a whole address, not as the bare name, Note; probablyMeant names the name you probably meant. "type\_filter\_too\_large": more than 100 names. On the list of every status, status=all, "CarriesRequiresStatusAll", "CarriesEmpty", "UnknownPredicate" and "UnknownLinkPlane" name an option it cannot use: carries, which selects terms by the field they bind, or linkPlane, which selects links by plane \(user, process, grant or classification\).

GET /base/terms and GET /base/registry/usage answer 400 "querystring must have required property 'q'", or 'term', when the word or the address is missing, and 400 "querystring must NOT have additional properties" for an option they do not take, such as cursor. A limit that is not a number answers 400 "querystring/limit must match pattern "^\[0-9\]{1,4}$"", one outside 1 to 100 "LimitOutOfRange", and an offset above 10,000 "OffsetOutOfRange". GET /base/registry/usage/bulk answers 400 "NoTermsNamed" when terms holds only commas, "TooManyTerms" with more than 100 addresses, and 400 "querystring must have required property 'terms'" when terms is left out.

404 "NotFound", with "No resource at" and the address, means GilbVeda has no term there. Capitals count: /base/t/note answers 404 where /base/t/Note answers 200. A module other than planguage-core, and a host the platform does not serve, answer 404 too. A kind GilbVeda does not have, asked at /base/kind/&lt;kind\>/parentless, is not refused: it answers 200 with no terms. 409 "IdentityCollision" means two terms claim the same address; the answer names the address instead of choosing one.

POST /base/term-requests, which checks whether a term already carries a meaning, and GET /base/life/taxa, which looks up a species, need [a person's sign-in token](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit) and [a new DPoP proof](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request): with no token the answer is 401 "This surface requires an authenticated caller \(no token presented\)". A DPoP proof is a short signed note your app makes for one request, naming its method and address \(RFC 9449\). A 503, such as "LookupUnavailable", means the platform could not answer this time; it is not a "MISS", so ask again later. These refusals are not in the Developer Guide, GilbPlatform's guide for people who build apps on it, yet; its chapter Dev.Guide.Vocabulary, https://appbuilder.gilb.com/base/e/06gkzpwtj1wm58yf6zng0xdtbm, shows how to read a term. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 \(live at https://id.gilb.com/version, read 2026-11-11\): src/routes/vocab.ts:504-572 \(VocabSelectorError: SelectorRepeated, LimitMalformed, LimitOutOfRange "⛔ Not clamped", CursorMalformed\), :921-1000 \(GET /base/vocab: unregistered host 404; CarriesRequiresStatusAll, CarriesEmpty, SelectorCombinationUnsupported, NodeKindEmpty\), :1000-1060 \(UnknownLinkPlane, linkPlane combination, UnknownPredicate\), :1132 \(409 IdentityCollision on a published collision\), :1196-1225 \(module 404\), :401-432 \(search and usage query schemas\), :1263-1290 \(LimitOutOfRange, OffsetOutOfRange\), :1371-1538 \(usage reads; NoTermsNamed, TooManyTerms\), :716-769 \(parentless: unknown kind 200 empty\), :183-191 \(collisionReply\); src/read/type-name-selector.ts:39, :71-110 \(type\_token\_unresolved with probablyMeant; type\_filter\_too\_large\); src/routes/\_http.ts:26-28, :52-59 \(404 NotFound "No resource at ..."\); src/server/app.ts:244-256 \(4xx body: error, message, details\); src/auth/principal.ts:550-567 \(401 text\); src/termrequest/answers.ts:109-110 \(503 LookupUnavailable\); src/routes/life-mint.ts:428-446. Public reads, no token, 2026-11-11, on https://veda.gilb.com/base: /vocab?limit=0 and limit=2001 400 LimitOutOfRange \(limit, max 2000\); limit=abc 400 LimitMalformed; limit=5&amp;limit=6 400 SelectorRepeated; cursor=zzz 400 CursorMalformed; type=Note&amp;limit=5 400 SelectorCombinationUnsupported; type=t:Note 400 type\_token\_unresolved, probablyMeant Note; 101 type names 400 type\_filter\_too\_large; nodeKind= 400 NodeKindEmpty; linkPlane=foo&amp;status=all 400 UnknownLinkPlane; carries=a:title 400 CarriesRequiresStatusAll; status=all&amp;carries= 400 CarriesEmpty; carries=a:nosuchxyz 400 UnknownPredicate; /vocab/base-internal and /vocab/nosuch 404 NotFound; /t/note and /a/Title 404 "No resource at ..."; /terms 400 "querystring must have required property 'q'"; /terms?cursor 400 additional properties; limit=101 400 LimitOutOfRange; offset=10001 400 OffsetOutOfRange; limit=abc 400 "querystring/limit must match pattern "^\[0-9\]{1,4}$""; /kind/foo/parentless 200 {terms: \[\], complete: true}; /t/NoSuchXyz/children 404; https://life.gilb.com/base/life/taxa 401. Dev.Guide.Errors \(A 06gkzpwxmnxf90zcc3mzc757xg\): no vocabulary read refusal in it. Shared sentences: term, DPoP proof, capitals count.

## For developers

### TypeScript: read-vocabulary.ts

```typescript
// A refused vocabulary read changes nothing; its body names the cause. No token is needed.
type Refusal = { error: string; message: string; [detail: string]: unknown };

export async function readVocabulary(url: string): Promise<unknown | null> {
  const res = await fetch(url);
  if (res.ok) return res.json();
  const body = (await res.json().catch(() => ({ error: "", message: "" }))) as Refusal;
  if (res.status === 404) return null; // no term at this address (capitals count)
  if (res.status === 400) throw new Error(`fix the request, ${body.error}: ${body.message}`);
  if (res.status === 409) throw new Error(`two terms claim this address: ${body.message}`);
  throw new Error(`vocabulary read answered ${res.status}; ask again later`);
}
```
