Why was my write refused?
Short answer
A refused write changes nothing; its error names the cause: 400 for a spelling or a value, 409 for a clash with what is stored.
Deeper
A write refusal is GilbPlatform's answer when it will not store what you sent. Its body has error and message, and nothing is written. 403 and 404 mean you may not write there: the answer on what access refusals mean. 412 and 428 are about If-Match: the answer on writing only if nothing changed. The rest are below.
400 InvalidDatomError for a spelling: a bare type name, such as Note, answers Type 'Note' is not a legal type notation (a bare slug carries no namespace)…; so do a: in the type place, apart from a few old names, and t: in a fact-name place, and two spellings of one fact in one body. Write types as t:<Type> and fact names as a:<name>. A full address on another host is kept as you wrote it, not refused, so the same meaning written two ways is stored twice.
400 for an empty or missing value. A fact set to null answers "Attribute '<name>' has a null value; datoms cannot assert null — omit the attribute or retract it to express no value."; to remove a fact, send it as null in a PATCH, or leave it out of a PUT. A body with no facts key answers body must have required property 'facts', and a key the route does not list, such as one of your own, is refused too. PUT /base/e/<new id> or POST /base/ingest with no facts at all answers A create needs at least one fact…. A request with Content-Type: application/json and no body answers 400 FastifyError, Body cannot be empty when content-type is set to 'application/json', even where no body is needed, such as ending a relation: send no Content-Type, or {}.
409 UndefinedTermError: a fact name that no term in GilbVeda, the shared list of terms, defines, and 409 TermBindingTieError: a name two terms claim at once. Today this check does not run for a person's or an organisation's vault, where such a fact is stored: check each name against GilbVeda yourself. Ask for a missing term; never make up a name of your own. 409 HierarchyConstraintError: an a:subTypeOf, the link from a term to its is-a parent, the broader GilbVeda term that a term is a kind of, that would give a term two parents, make it its own parent, or close a circle; a:partOf is not bound by this.
409 EntityEndedError: a PATCH or other part change to an ended record, a deleted one; only a PUT of all its facts brings it back. 409 EntityVaultUnresolvedError: a record that names no vault; only the platform's owner sees this, others get 403. 409 IdentityCollisionError, on PUT /base/e/<id>: another record was made with exactly the same facts; it is lasting, so change the facts rather than send it again. 409 write_conflict, with Retry-After: 0: "The record was changed by another write at the same time; nothing was written. Send the request 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.Vocabulary, https://appbuilder.gilb.com/base/e/06gkzpwtj1wm58yf6zng0xdtbm. 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; code read at 498d29a0): src/server/app.ts:236-257 (409 write_conflict + Retry-After 0 and its message :236-242; every 4xx with statusCode answers {error: err.name, message, ...details} :245-257), :340-341 (Ajv removeAdditional false: an extra body key is refused, not dropped); src/write/errors.ts:11-17 (InvalidDatomError 400), :30-34 (WriteForbiddenError 403), :63-71 (EntityEndedError 409, message), :82-93 (EntityVaultUnresolvedError 409), :133-155 (IdentityCollisionError 409, PERMANENT ... retrying will not clear it), :395-413 (HierarchyConstraintError 409: multi-parent, self-parent, cycle), :663-694 (UndefinedTermError 409, details), :724-755 (TermBindingTieError 409); src/write/normalize.ts:1-60 (the notation rules T1-T7, A1-A8; T4 :28-31 a few old a: type names mapped, not refused; foreign-host addresses kept), :264-271 and :312 (type message), :303-306 (old names), :324-357 (attribute messages), :476-480 (two spellings in one state); src/write/ingest.ts:1315-1317 (FACTLESS_CREATE_REFUSED text), :1452-1457 (POST /base/ingest with no fact), :1630-1641 (no vault: 409 to the owner, 403 to others), :1760-1780 (a create with no facts :1762-1764; EntityEndedError :1772-1780), :307-327 (null; message :321-324), :2336-2345 (identity collision); src/routes/relation.ts:259 (a:relationSelf stamped into every relation, so PUT /base/r/:id does not meet IdentityCollisionError); src/write/hierarchy-guard.ts:18-28 (is-a only; part-of and connected-to not guarded: ingest.ts:1956-1974); migrations/1784200000000_c161-term-admission-row-guard.sql:62-71 and 1784900000000_c206-term-admission-master-vault.sql:10-20 (the term guard admits everything in a store with no ontology seeded: why a person vault stores an undefined fact); src/lws/routes.ts:1156-1166 (body schema: required facts, additionalProperties false); src/lws/crud.ts:228-236 (a:lwsSelf: the /lws doors do not meet IdentityCollisionError); src/routes/relation.ts:294-346 (POST /base/r/:id/end, no body read); src/server/app.ts:440-459 (only form bodies get an added parser; JSON keeps Fastify's own); package-lock.json at 498d29a0: fastify 5.8.5, whose lib/errors.js:122-126 FST_ERR_CTP_EMPTY_JSON_BODY reads Body cannot be empty when content-type is set to 'application/json' (400; library text). Production, 2026-11-11, no token, a POST to a relation address that does not exist, with Content-Type: application/json and no body (refused, nothing written; see the report): 400 {error:FastifyError,message:Body cannot be empty when content-type is set to 'application/json'}. Dev.Guide.Errors (A 06gkzpwxmnxf90zcc3mzc757xg, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied); Dev.Guide.Vocabulary (A 06gkzpwtj1wm58yf6zng0xdtbm, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied) Errors.Answer01 (400 body must have required property 'facts', verified 2026-10-15), Answer02, Answer26, Answer27 (Today not produced for a person or organisation vault, 2026-10-15); Vocabulary.Refusals (the table; the bare Note message; full address kept), .AskForTerm. Rows: Developer.WriteRefusedNotation, WriteRefusedHierarchy, WriteRefusedUndefinedTerm, WriteRefusedEmptyOrNull, WriteRefusedEndedOrNoVault, EmptyJsonBodyRefused (and the RecordWrite row's 409 IdentityCollisionError).
Checked against GilbApp d529620.