The API vocabulary

Generated. Do not edit by hand. Regenerate with conda run -n tckdb_env python backend/scripts/generate_api_vocabulary.py. Every token below is read from the code that defines it — the enum members, the public-reference registry, the code catalogue, the trust rubrics — so this document cannot describe a word TCKDB does not use. A term added upstream and not regenerated here turns the CI gate red.

What this is

TCKDB answers in tokens: not_reviewed, hard_failed, matched_direction, spc_01h9k…, smiles_too_long. Each of them is a real distinction the code takes seriously, and most of them are not guessable from the string. This is the list, with a plain-language definition for each and the concrete case where the meaning turns on something non-obvious.

It assumes you know chemistry and does not assume you know this database. So substructure gets a sentence about which algorithm ran and chebyshev does not appear at all: a Chebyshev fit means the same thing here as everywhere else, and explaining it would bury the tokens that mean something only inside TCKDB.

What is in, and what is not

A token is here when both of these hold:

1. You can meet it. The literal string can appear in a public API response body. This half is checked mechanically: app/glossary/reachability.py computes the vocabulary the read schemas and the trust fragment can serialise, and the test suite refuses an entry outside that set. A word only an administrator or an internal service sees is not vocabulary you need.
2. Chemistry does not decode it. The token says something about TCKDB's own process — how a record was reviewed, how much evidence stands behind it, how your query matched, how a record is named, or why a request was refused.

Three things are deliberately absent:

• The scientific checks. What TCKDB guarantees about chemistry is its own generated document: the scientific check register. Copying it here would create a second copy to keep in step.
• Reaction family names. A reaction's family is an RMG identifier — H_Abstraction, Disproportionation, intra_H_migration — carried verbatim. There are 125 of them seeded and the reaction_family table holds only an id, that name and a timestamp: no display name and no description column exist, so "Hydrogen Abstraction" is not a fact this database holds and inventing 125 of them here would be fiction with a generator's credibility. Recorded as a gap; giving families human-readable names is a schema decision, not a documentation one.
• A definition per refusal code. The code catalogue deliberately carries no prose — the refusal already has a sentence, the one you receive in detail, and a second copy would drift from it. The code table below therefore renders the facts the catalogue does hold, and invents nothing.

What this covers

Kind of token	Count	Read from
Status, badge and query words	123	28 enums, declared in backend/app/glossary/declarations.py
Identifier prefixes	43	backend/app/services/public_refs.py
Trust check names	174	backend/app/services/trust/rubrics.py
Refusal codes a caller can receive	334	backend/app/api/code_catalogue.py
total	674

How a record is named

Every record TCKDB serves is named by a public reference — a short prefix, an underscore, and 26 characters: spc_, rxn_, cg_, lot_. The prefix tells you what kind of record it is, and it is the only part you are meant to read.

There are two kinds of reference, and the difference matters more than it looks:

• Content-derived — computed from the record's own canonical identity. The same species has the same reference on every TCKDB instance, so two deployments can be compared, and a reference of this kind is a claim about what the thing is.
• Opaque — 130 random bits. It identifies one row in one database and nothing more. Two instances that hold the same calculation give it different opaque references, and that is correct: an event is not the same event because it looks alike.

Nothing in the string says which kind you are holding, which is why this table exists.

Content-derived prefixes (13)

Prefix	Names a	Same on every instance?
cas_	conformer assignment scheme	yes
csch_	composite scheme	yes
ecs_	energy correction scheme	yes
fsf_	frequency scale factor	yes
geom_	geometry	yes
lit_	literature	yes
lot_	level of theory	yes
rxn_	chem reaction	yes
soft_	software	yes
spc_	species	yes
srel_	software release	yes
wfr_	workflow tool release	yes
wft_	workflow tool	yes

Opaque prefixes (30)

Prefix	Names a	Same on every instance?
aie_	artifact integrity event	no — one row, one database
art_	calculation artifact	no — one row, one database
calc_	calculation	no — one row, one database
cg_	conformer group	no — one row, one database
co_	conformer observation	no — one row, one database
cpol_	curation policy	no — one row, one database
gasch_	group additivity scheme	no — one row, one database
kdet_	kinetics determination	no — one row, one database
kin_	kinetics	no — one row, one database
mpo_	molecular property observation	no — one row, one database
net_	network	no — one row, one database
nkdet_	network kinetics determination	no — one row, one database
nkin_	network kinetics	no — one row, one database
nsolve_	network solve	no — one row, one database
rel_	dataset release	no — one row, one database
rman_	release manifest	no — one row, one database
rpa_	record reproducibility assessment	no — one row, one database
rsel_	release selection	no — one row, one database
rxe_	reaction entry	no — one row, one database
sdet_	structure determination	no — one row, one database
sfnd_	structure evidence finding	no — one row, one database
sm_	statmech	no — one row, one database
smd_	statmech model declaration	no — one row, one database
spe_	species entry	no — one row, one database
sra_	submission rights attestation	no — one row, one database
sub_	submission	no — one row, one database
thm_	thermo	no — one row, one database
trn_	transport	no — one row, one database
ts_	transition state	no — one row, one database
tse_	transition state entry	no — one row, one database

What a person has said about a record

Review status

On the wire: review.status on a record, trust.review_status inside the trust fragment, the review_summary counts on a search response, and the min_review_status filter on a request.

What a human curator has said about one scientific record. It is the only vocabulary here that reports a person's judgement; everything under What TCKDB can check by itself is computed and says nothing about whether anybody has looked.

Token	What it means
not_reviewed	Nobody has looked at this record. It is the state every deposit lands in, and it is a statement about TCKDB's attention, not about the science: an unreviewed record can be perfectly good.
under_review	A curator has this record open. It is entered deliberately by a curator, never by depositing, which is the whole difference from not_reviewed. For example: Until 2026-08-24 every deposit was stamped under_review on arrival, so 1,153 records on the hosted database claimed somebody was looking at them when nobody was. Revision c1d8f4a25b30 moved them to not_reviewed. If you read the hosted API before that date, under_review there meant nothing at all.
approved	A curator reviewed the record and accepts it. This is the floor the curated read profile draws at: a curated read returns approved records and nothing below them.
rejected	A curator reviewed the record and does not accept it. Absent from results unless the request asks for it with include_rejected=true.
deprecated	The record should no longer be used — superseded by a better one, or withdrawn. It is kept rather than deleted so an existing citation still resolves. Absent from results unless the request asks with include_deprecated=true.

A response lists records in a fixed display order, echoed in request.sort. The review part of it is defined once, in docs/specs/browse_order.md; it is not a scientific preference.

What TCKDB can check by itself

Trust status (the evidence badge)

On the wire: trust.trust_status, and trust.evidence.label beside it.

How much of the evidence TCKDB expects for this kind of record is actually attached. It is completeness, not quality: a well_supported rate coefficient is one whose paperwork is complete, not one TCKDB says is right. The first five are the completeness ladder, computed as a weighted ratio of the checks in the record's rubric; hard_failed is not on that ladder at all.

Token	What it means
well_supported	Evidence completeness of 0.90 or better and every check the rubric marks required passed. The required-checks gate is separate from the ratio: a record cannot reach this badge on volume of evidence alone.
mostly_supported	Evidence completeness of 0.75 or better.
partial	Evidence completeness of 0.50 or better.
sparse	Evidence completeness of 0.25 or better.
unsupported	Evidence completeness below 0.25. Incomplete, which is not the same as wrong — this is the expected badge for an old record deposited before TCKDB asked for much.
hard_failed	A discrete structural failure was found, and the badge is set by that finding rather than by the ratio. Always read trust.evidence.hard_fail_reason beside it: the reason says whether the record contradicts itself, or whether TCKDB can no longer produce the evidence it rests on.

Check outcomes

On the wire: the values of the trust.evidence.checks map, whose keys are the check names listed further down.

What one deterministic check found. Four states and never a boolean: missing and not_applicable are different answers and collapsing them would penalise a record for a question nobody could ask.

Token	What it means
passed	The check's condition held. Positive evidence, and it counts.
missing	The check applied and did not pass. It counts against the record: it is inside the denominator and outside the numerator of the completeness ratio.
warning	The check applied, the underlying signal is tri-state, and the result is informational. Warning-kind checks carry zero weight, so this never moves the completeness ratio.
not_applicable	The question could not be asked of this record, so the check is excluded from both the numerator and the denominator — it neither helps nor hurts. For example: When geometry_validation_present_for_source_calculations is missing, there is no validation verdict to inspect, so geometry_validation_not_failed_for_source_calculations is not_applicable: "did it fail?" has no answer. Rendering that as false would count the same absence twice.

Check names are written as assertions, so read the name and the value together: "ts_graph_or_smiles_present": "missing" means there is no SMILES or mol blob on this transition-state entry. Until 2026-08-24 the same fact was reported as the string ts_graph_or_smiles_present sitting inside an array named missing_checks, which read as a double negative; the four arrays passed_checks / missing_checks / warning_checks / not_applicable_checks were replaced by this one map. If you are reading a client written before then, that is what those arrays were.

Hard-fail reasons

On the wire: trust.evidence.hard_fail_reason, and only when trust_status is hard_failed.

Why a record was hard-failed. Each names one discrete, evidenced structural failure — never a low score. Six of them (invalid_lj_pair, no_transport_property_present, no_thermo_representation_present, invalid_external_symmetry, invalid_torsion_dimension, multiplicity_invalid) re-derive a rule the upload path already refuses, so seeing one means the record reached the database by some route that skipped upload validation — an archive restore, a data migration, a bulk importer or direct SQL. Treat those as an incident to trace, not as a record that merely scored badly.

Token	What it means
calculation_missing	The calculation this verdict is about could not be loaded at all.
calculation_rejected	The calculation's quality is rejected — a curator marked it unusable.
kinetics_missing	The kinetics record could not be loaded.
statmech_missing	The statistical-mechanics record could not be loaded.
thermo_missing	The thermochemistry record could not be loaded.
transport_missing	The transport record could not be loaded.
species_entry_missing	The record does not point at the species entry it is supposed to describe, so there is nothing to attribute it to.
no_thermo_representation_present	A thermochemistry record carrying no thermochemistry: no NASA polynomial, no Wilhoit, no scalar values, no points. A backstop — the upload path refuses this.
no_transport_property_present	A transport record carrying no transport property at all. A backstop — the upload path refuses this.
invalid_lj_pair	The Lennard-Jones parameters are not a usable pair. A backstop — the upload path refuses this.
invalid_temperature_range	The record's validity range is definitionally impossible: a non-positive temperature, or a minimum above the maximum. Note that a single-temperature range (tmin == tmax) is legal and does not fire this, and there is no upper bound — shock-tube and plasma chemistry are not structurally broken.
invalid_external_symmetry	The external symmetry number is below 1. A backstop — the upload path refuses this.
invalid_torsion_dimension	A hindered-rotor torsion declares a dimension below 1. A backstop — the upload path refuses this.
geometry_validation_failed	Historic: stored trust results under the version 1 rubrics carried this when an automated geometry comparison failed. Version 2 rubrics no longer hard-fail on it; the failure is a warning on the geometry check.
artifact_integrity_failed	The stored bytes behind one of this calculation's artifacts no longer match their digest, or are gone. This one is a statement about TCKDB's custody of the evidence, not about the depositor's science: the record may be perfectly good and we can no longer show you what it rests on. It reflects the latest observation per artifact, so a restored object clears it.
missing_required_identity	The kinetics record does not identify a complete reaction — no reaction entry, or a side with no participants on it.
source_calculation_hard_failed_for_required_role	A calculation this record depends on for a role it cannot do without — a reactant or product energy, the TS energy, the frequencies — is itself hard-failed. The failure is inherited, so read that calculation's own reason.
transition_state_entry_missing	The transition-state entry could not be loaded.
transition_state_parent_missing	The entry does not point at the transition state it is an entry for.
reaction_entry_missing	The parent transition state names no reaction entry, so the TS belongs to no reaction.
ts_entry_status_rejected	The transition-state entry's own status is rejected.
multiplicity_invalid	The spin multiplicity is below 1. A backstop — the upload path refuses this.
all_source_calculations_hard_failed	Every calculation supporting this transition-state entry is itself hard-failed, so nothing is left to support it.
geometry_validation_failed_for_source_calculation	Historic: stored version 2 transition-state trust results carried this when a supporting calculation failed the automated geometry comparison. Version 3 no longer hard-fails on it; it is a warning.
frequency_source_has_zero_imaginary_modes_for_validated_ts	Historic: stored version 2 transition-state trust results carried this when the latest frequency result reported no imaginary mode. Version 3 issues no frequency verdict; the same fact is the warning no_frequency_result_lacks_an_imaginary_mode, and the scoped judgement (does a usable result on the evaluated geometry contradict the saddle claim) is the structure assessment's.
frequency_source_reaction_coordinate_not_designated_for_validated_ts	Historic: stored version 2 transition-state trust results carried this when the latest frequency result reported several imaginary modes without a designated reaction coordinate. Version 3 issues no frequency verdict; the missing designation is the missing check reaction_coordinate_designated_for_ts, and the structure assessment reports it as the unresolved reaction_coordinate_not_established.

Transition-state structure assessment status

On the wire: trust.structure_assessment.status on a transition-state entry's trust block.

Whether TCKDB asked its structure assessment about the saddle this entry declares, and what came back. The assessment answers one fixed question, echoed in trust.structure_assessment.task: does a declared target have the evidence for a first-order saddle. It is advisory. It never changes the trust badge, the completeness numbers or is_certified.

Token	What it means
assessed	The entry declares at least one saddle target and the assessment ran under the read profile of this request. Read outcome and units. The same answer comes from sending task to the entry's evidence-selection endpoint.
no_declared_target	The entry declares no saddle target that this request may see, so there is nothing to assess. This is not a missing check: the badge never required a declaration.
not_assessed_on_lists	This response lists several entries (a search, the sibling entries of a detail read, a reaction document), and the assessment runs on a single-entry detail read only. So the same entry shows the same status on every list. Read the entry's own page for the assessment.
not_assessed_over_bound	The assessment refused because the entry's evidence is over the server's fixed size limits, and nothing is inferred from part of it. refusal_code names the limit; the evidence-selection endpoint answers the same refusal.

Transition-state structure assessment outcome

On the wire: trust.structure_assessment.outcome on a transition-state entry's trust block.

What the structure assessment found for the declared saddle targets, for the question in trust.structure_assessment.task. Only an evidence question is asked, so these are the only three outcomes. Anything but qualified_evidence means the declared target needs investigation; none of them says the transition state is disproved.

Token	What it means
qualified_evidence	At least one declared target has the evidence for the question asked, and qualifying_refs names it. This is scoped to that question and is not a certificate. A contested target beside it still raises the declared_saddle_target_qualifies warning.
no_applicable_candidate	No declared target qualifies: each is either contradicted by its own evidence or lacks a fact the question needs. units says which, per target, as codes.
evidence_conflict	The declared evidence disagrees with itself: a target with both a supporting and a contradicting determination, or a target whose only failure is a recorded finding against its evidence.

Reproducibility grade

On the wire: assessments.reproducibility.grade.

How far somebody else could get with what was deposited. An evidence ladder, independent of both the review status and the trust badge, and a statement about completeness of the deposit rather than a promise of bitwise-identical output. Only a calculation can be graded above described: a thermo or kinetics record keeps the limits of the sources behind it. An assembled composite energy, which ran no program of its own, is graded on its inputs instead: it reaches a level only when every calculation it cites does, and only while its stated total still follows from them. A statmech record is graded on the same checks whether a species entry or a transition-state entry owns it.

Token	What it means
insufficient	The record does not even describe what was done well enough to audit.
described	What the record is and the scientific context around it are recorded. The ceiling for every non-calculation record.
auditable	The preserved evidence can be inspected: the output bytes are there and were read back through the artifact path.
rerunnable	The deposit is complete enough to attempt a rerun — preserved inputs, an execution-parameter snapshot, the upstream dependency snapshot, and no warnings about artifact bytes TCKDB could not read. It is not a claim that a rerun would reproduce the numbers.

Composite energy verification

On the wire: composite_energy_verification.state on a composite calculation, and the same block on levels of a thermo, statmech or kinetics record whose energy comes from a composite.

How far a composite energy (CBS-QB3, G4, a CCSD(T)/CBS extrapolation, a focal-point sum) has been checked by TCKDB. Computed on every read and never stored; TCKDB never stores a total it computed itself, so an assembled composite's number is always the one the depositor sent. It says nothing about whether a person has looked, and nothing about whether the recipe is a good one.

Token	What it means
recomputed	An assembled composite whose stored inputs, run through its scheme just now, give the total it states, within a tolerance that scales with how many rounded numbers went into the sum. Because it is recomputed on every read, an input energy deposited later is picked up.
recompute_mismatch	The same recomputation disagrees. This can only happen after the fact, because a total that disagreed was refused at upload: an input's stored energy is no longer what the total was checked against (a single point whose energy a later log upload filled in, say; an accepted input cannot change). difference_hartree is the stated total minus the recomputed one.
log_reconciled	A program run (one program printed the final number) whose attached output log was compared at upload and confirmed every number the deposit stated.
program_reported	A program run with no confirming log: none was attached, or the one attached could not confirm it. The reason says which, and names a log that disagreed (log_mismatch, log_method_mismatch) rather than hiding it.
unverifiable	The check cannot be made: an input or one of its energy components is not stated, the split of an input's correlation energy matches neither convention for (T), or no energy was stated at all. The reason names which; nothing is guessed.

Check names

On the wire: the keys of the trust.evidence.checks map.

A check name is an assertion, so read it together with its value: "irc_evidence_present": "missing" means there is no IRC evidence. The names below are the rubrics' own, and each explanation is the sentence the rubric itself carries — not a paraphrase written here.

kind decides what a failure costs: required — failing it stops the record reaching well_supported, however good the ratio is; optional — contributes to completeness; its absence blocks no badge; warning — informational; carries zero weight. weight is that check's share of the completeness ratio.

Which rubric applies is decided by the kind of record, and for a statmech record by what owns it (computed_statmech for a species entry, computed_ts_statmech for a transition-state entry): computed_calculation (v1), computed_kinetics (v1), computed_statmech (v1), computed_thermo (v1), computed_transition_state (v2), computed_transport (v1), computed_ts_statmech (v1).

Check	Rubric	Kind	Weight	What it asks
arrhenius_parameters_complete	computed_kinetics	required	1	Arrhenius-family kinetics should include A, A units, n, and Ea.
arrhenius_units_present	computed_kinetics	optional	1	Arrhenius A units should be populated for Arrhenius-family kinetics.
artifacts_present	computed_calculation	optional	1	At least one calculation_artifact (log, input, ...) should be retained.
at_least_one_thermo_representation_present	computed_thermo	required	1	Thermo must have scalar, NASA-7, NASA-9, Wilhoit, or tabulated-point evidence.
calculation_dependencies_present	computed_transition_state	optional	1	At least one calculation_dependency edge should document the source-set DAG.
calculation_dependencies_present_when_expected	computed_calculation	optional	1	Calculations derived from another step (freq/sp/irc/scan) should record their upstream parent.
calculation_has_owner	computed_calculation	required	1	Calculation must be owned by exactly one species_entry or transition_state_entry.
calculation_type_present	computed_calculation	required	1	Calculation.type must be set.
charge_present	computed_transition_state	required	1	transition_state_entry.charge must be set.
chem_reaction_present	computed_transition_state	optional	1	Parent reaction_entry should resolve to a chem_reaction.
correction_scheme_literature_present	computed_thermo	optional	1	A cited software-scoped correction scheme should cite the literature its parameters come from.
correction_scheme_software_release_present	computed_thermo	optional	1	A cited software-scoped correction scheme (atom_energy, bac_petersson, bac_melius) should declare which software release computed its parameters.
declared_saddle_target_qualifies	computed_transition_state	warning	0	When the entry declares a saddle target: the structure assessment's first-order saddle question, asked of the evidence alone, finds a declared target that qualifies and no contested target (advisory, zero weight). A warning means the declared target needs investigation, not that the transition state is disproved, and no warning certifies nothing. The scoped answer is trust.structure_assessment; it is computed on a single transition-state entry read and not on lists.
dipole_present	computed_transport	optional	1	Dipole evidence should be populated when this representation is present.
dipole_source_present_if_dipole_present	computed_transport	optional	1	Computed dipole transport evidence should link a dipole source calculation.
epsilon_present	computed_transport	optional	1	Lennard-Jones transport should include epsilon/k.
external_symmetry_present	computed_statmech	optional	1	External symmetry number should be recorded.
external_symmetry_present	computed_ts_statmech	optional	1	External symmetry number should be recorded.
extra_imaginary_modes_not_flagged	computed_transition_state	warning	0	Recorded ADR 0012 structural flag: an extra imaginary mode at or above the protocol's tau (advisory).
freq_source_present	computed_statmech	optional	1	Computed statmech should link a frequency source calculation when available.
freq_source_present	computed_thermo	optional	1	Computed thermo should link a frequency source calculation when available.
freq_source_present	computed_ts_statmech	optional	1	Computed statmech should link a frequency source calculation when available.
frequency_scale_factor_present_if_applicable	computed_statmech	optional	1	Frequency-derived statmech should record a frequency scale factor.
frequency_scale_factor_present_if_applicable	computed_thermo	optional	1	Frequency-derived thermo should record its frequency scale factor when schema support exists.
frequency_scale_factor_present_if_applicable	computed_ts_statmech	optional	1	Frequency-derived statmech should record a frequency scale factor.
frequency_source_present	computed_kinetics	optional	1	Frequency source calculations should be linked when available.
full_transport_source_present	computed_transport	optional	1	Computed transport should link a full-transport source calculation when available.
geometry_validation_not_failed_for_source_calculations	computed_kinetics	warning	0	Source calculation geometry validation is warning (advisory).
geometry_validation_not_failed_for_source_calculations	computed_statmech	warning	0	Source calculation geometry validation is warning (advisory).
geometry_validation_not_failed_for_source_calculations	computed_thermo	warning	0	Source calculation geometry validation is warning (advisory).
geometry_validation_not_failed_for_source_calculations	computed_transition_state	warning	0	Source calculation geometry validation is warning (advisory).
geometry_validation_not_failed_for_source_calculations	computed_transport	warning	0	Source calculation geometry validation is warning (advisory).
geometry_validation_not_failed_for_source_calculations	computed_ts_statmech	warning	0	Source calculation geometry validation is warning (advisory).
geometry_validation_passed_or_warning	computed_calculation	warning	0	Geometry validation status is warning (advisory).
geometry_validation_present	computed_calculation	optional	1	Opt calculations should carry geometry-validation evidence.
geometry_validation_present_for_source_calculations	computed_kinetics	optional	1	Strong source calculations should carry geometry-validation evidence.
geometry_validation_present_for_source_calculations	computed_statmech	optional	1	Strong source calculations should carry geometry-validation evidence.
geometry_validation_present_for_source_calculations	computed_thermo	optional	1	Strong source calculations should carry geometry-validation evidence.
geometry_validation_present_for_source_calculations	computed_transition_state	optional	1	At least one opt/irc/path_search source calc should carry geometry validation.
geometry_validation_present_for_source_calculations	computed_transport	optional	1	Strong source calculations should carry geometry-validation evidence.
geometry_validation_present_for_source_calculations	computed_ts_statmech	optional	1	Strong source calculations should carry geometry-validation evidence.
imaginary_frequency_count_recorded	computed_transition_state	optional	1	Representative freq result (the one a declared saddle target pins, else the newest attached) should record n_imag.
imaginary_frequency_value_present	computed_transition_state	optional	1	Representative freq result (the one a declared saddle target pins, else the newest attached) should record the imaginary-mode value (cm-1).
input_geometry_present	computed_calculation	required	1	At least one input geometry must be linked.
irc_evidence_present	computed_kinetics	optional	1	IRC evidence should be linked when available.
irc_evidence_present	computed_transition_state	optional	1	IRC calculation present (additive only) -- this checks that an IRC calculation exists in the source set, not that structured pass/fail validation evidence was deposited.
is_linear_present	computed_statmech	optional	1	Linearity should be explicitly recorded.
is_linear_present	computed_ts_statmech	optional	1	Linearity should be explicitly recorded.
kinetics_model_present	computed_kinetics	required	1	Kinetics.model_kind must be set.
level_of_theory_present	computed_calculation	required	1	Calculation must resolve to a level_of_theory row.
lj_pair_present_if_applicable	computed_transport	optional	1	Lennard-Jones transport should include both sigma and epsilon/k.
master_equation_or_fit_source_present_if_applicable	computed_kinetics	optional	1	Explicit master-equation or fit-source roles count when present.
multiplicity_present	computed_transition_state	required	1	transition_state_entry.multiplicity must be set.
multiplicity_valid	computed_transition_state	required	1	transition_state_entry.multiplicity must be >= 1.
nasa_coefficients_present	computed_thermo	optional	1	NASA thermo should include a complete coefficient block.
no_frequency_result_has_undesignated_imaginary_modes	computed_transition_state	warning	0	No attached frequency result with a recorded count reports several imaginary modes without designating which is the reaction coordinate (advisory; the badge does not certify the saddle). A warning means that attached result needs investigation, not that the transition state is disproved.
no_frequency_result_lacks_an_imaginary_mode	computed_transition_state	warning	0	No attached frequency result with a recorded count reports zero imaginary modes (advisory; the badge does not certify the saddle).
opt_source_present	computed_statmech	optional	1	Computed statmech should link an optimization source calculation when available.
opt_source_present	computed_thermo	optional	1	Computed thermo should link an optimization source calculation when available.
opt_source_present	computed_ts_statmech	optional	1	Computed statmech should link an optimization source calculation when available.
output_geometry_present	computed_calculation	optional	1	Geometry-producing calculation types should record an output geometry.
parameters_parsed	computed_calculation	optional	1	ESS execution parameters should be parsed (EAV rows or JSONB snapshot).
path_search_evidence_present	computed_kinetics	optional	1	Path-search evidence should be linked when available.
path_search_evidence_present	computed_transition_state	optional	1	Path-search (NEB/GSM/scan parent) evidence should be linked when available.
point_group_present	computed_statmech	optional	1	Point group should be recorded when known.
point_group_present	computed_ts_statmech	optional	1	Point group should be recorded when known.
polarizability_present	computed_transport	optional	1	Polarizability evidence should be populated when this representation is present.
polarizability_source_present_if_polarizability_present	computed_transport	optional	1	Computed polarizability transport evidence should link a polarizability source calculation.
product_energy_sources_present	computed_kinetics	optional	1	Product energy source calculations should cover all loaded products.
quality_recorded	computed_calculation	optional	1	An independent reviewer should have approved this calculation via record_review; self-declared CalculationQuality is not sufficient (decoupled from trust, see _check_quality_recorded).
reactant_energy_sources_present	computed_kinetics	optional	1	Reactant energy source calculations should cover all loaded reactants.
reaction_coordinate_designated_for_ts	computed_transition_state	required	1	Representative freq result (the one a declared saddle target pins, else the newest attached) must identify its reaction coordinate: one imaginary mode needs no designation, more than one does (ADR 0012).
reaction_entry_present	computed_kinetics	required	1	Kinetics must be attached to a reaction_entry.
reaction_entry_present	computed_transition_state	required	1	Parent transition_state must resolve to a reaction_entry.
result_block_present	computed_calculation	required	1	Calculation must have the result block matching its type (sp/opt/freq/irc/scan/path_search).
review_not_rejected_or_deprecated_if_applicable	computed_transition_state	required	1	TS-entry review/deprecation checks apply once record_review lookup is wired.
rigid_rotor_kind_present	computed_statmech	required	1	Rigid rotor treatment should be recorded.
rigid_rotor_kind_present	computed_ts_statmech	required	1	Rigid rotor treatment should be recorded.
rotational_relaxation_present	computed_transport	optional	1	Rotational-relaxation evidence should be populated when present.
scalar_thermo_present	computed_thermo	optional	1	Scalar H298 or S298 values should be populated when using scalar thermo.
scan_source_present_if_torsions_present	computed_statmech	optional	1	Torsion-bearing statmech should link scan source evidence.
scan_source_present_if_torsions_present	computed_ts_statmech	optional	1	Torsion-bearing statmech should link scan source evidence.
scf_stability_present_if_claimed	computed_calculation	optional	1	SCF stability evidence should be attached when claimed.
sigma_epsilon_pair_consistent	computed_transport	required	1	sigma_angstrom and epsilon_over_k_k must be both present or both absent.
sigma_present	computed_transport	optional	1	Lennard-Jones transport should include sigma.
software_release_present	computed_calculation	optional	1	Calculation should declare which software_release produced it.
source_calculation_artifacts_present	computed_kinetics	optional	1	At least one linked source calculation should retain an artifact.
source_calculation_artifacts_present	computed_statmech	optional	1	At least one linked source calculation should retain an artifact.
source_calculation_artifacts_present	computed_thermo	optional	1	At least one linked source calculation should retain an artifact.
source_calculation_artifacts_present	computed_transition_state	optional	1	At least one source calculation should retain an artifact.
source_calculation_artifacts_present	computed_transport	optional	1	At least one linked source calculation should retain an artifact.
source_calculation_artifacts_present	computed_ts_statmech	optional	1	At least one linked source calculation should retain an artifact.
source_calculation_has_non_hard_failed_evidence	computed_statmech	optional	1	Linked source calculations should avoid deterministic hard-fail signals.
source_calculation_has_non_hard_failed_evidence	computed_thermo	optional	1	Linked source calculations should avoid deterministic hard-fail signals.
source_calculation_has_non_hard_failed_evidence	computed_transition_state	required	2	At least one source calculation must avoid deterministic hard-fail signals.
source_calculation_has_non_hard_failed_evidence	computed_transport	optional	1	Linked source calculations should avoid deterministic hard-fail signals.
source_calculation_has_non_hard_failed_evidence	computed_ts_statmech	optional	1	Linked source calculations should avoid deterministic hard-fail signals.
source_calculation_lot_present	computed_kinetics	required	1	All linked source calculations should resolve to level_of_theory.
source_calculation_lot_present	computed_statmech	required	1	All linked source calculations should resolve to level_of_theory.
source_calculation_lot_present	computed_thermo	required	1	All linked source calculations should resolve to level_of_theory.
source_calculation_lot_present	computed_transition_state	required	1	Every source calculation must resolve to a level_of_theory.
source_calculation_lot_present	computed_transport	optional	1	All linked source calculations should resolve to level_of_theory.
source_calculation_lot_present	computed_ts_statmech	required	1	All linked source calculations should resolve to level_of_theory.
source_calculation_result_blocks_present	computed_kinetics	optional	1	Linked source calculations should have their expected result blocks.
source_calculation_result_blocks_present	computed_statmech	optional	1	Linked source calculations should have their expected result blocks.
source_calculation_result_blocks_present	computed_thermo	optional	1	Linked source calculations should have their expected result blocks.
source_calculation_result_blocks_present	computed_transport	optional	1	Linked source calculations should have their expected result blocks.
source_calculation_result_blocks_present	computed_ts_statmech	optional	1	Linked source calculations should have their expected result blocks.
source_calculation_software_present	computed_kinetics	optional	1	All linked source calculations should declare software_release.
source_calculation_software_present	computed_statmech	optional	1	All linked source calculations should declare software_release.
source_calculation_software_present	computed_thermo	optional	1	All linked source calculations should declare software_release.
source_calculation_software_present	computed_transition_state	optional	1	Every source calculation should declare a software_release.
source_calculation_software_present	computed_transport	optional	1	All linked source calculations should declare software_release.
source_calculation_software_present	computed_ts_statmech	optional	1	All linked source calculations should declare software_release.
source_calculation_workflow_tool_present	computed_statmech	optional	1	Statmech or at least one source calc should declare workflow-tool release metadata.
source_calculation_workflow_tool_present	computed_thermo	optional	1	Thermo or at least one source calc should declare workflow-tool release metadata.
source_calculation_workflow_tool_present	computed_transition_state	optional	1	At least one source calculation should declare a workflow_tool_release.
source_calculation_workflow_tool_present	computed_transport	optional	1	Transport or at least one source calc should declare workflow-tool release metadata.
source_calculation_workflow_tool_present	computed_ts_statmech	optional	1	Statmech or at least one source calc should declare workflow-tool release metadata.
source_calculations_present	computed_kinetics	required	1	At least one kinetics_source_calculation row should support computed kinetics.
source_calculations_present	computed_statmech	required	1	At least one statmech_source_calculation row should support computed statmech.
source_calculations_present	computed_thermo	required	1	At least one thermo_source_calculation row should support computed thermo.
source_calculations_present	computed_transport	optional	1	At least one transport_source_calculation row should support computed transport.
source_calculations_present	computed_ts_statmech	required	1	At least one statmech_source_calculation row should support computed statmech.
sp_or_composite_source_present	computed_statmech	optional	1	Computed statmech may link single-point or composite supporting evidence.
sp_or_composite_source_present	computed_ts_statmech	optional	1	Computed statmech may link single-point or composite supporting evidence.
sp_or_composite_source_present_if_applicable	computed_thermo	optional	1	Computed thermo should link single-point or composite energy evidence when applicable.
species_entry_present	computed_statmech	required	1	Statmech must be attached to a species_entry.
species_entry_present	computed_thermo	required	1	Thermo must be attached to a species_entry.
species_entry_present	computed_transport	required	1	Transport must be attached to a species_entry.
statmech_not_rejected_or_deprecated_if_applicable	computed_statmech	optional	1	Statmech rejection/deprecation checks apply once modeled.
statmech_not_rejected_or_deprecated_if_applicable	computed_ts_statmech	optional	1	Statmech rejection/deprecation checks apply once modeled.
statmech_origin_is_computed	computed_statmech	required	1	Statmech.scientific_origin should be computed for this rubric.
statmech_origin_is_computed	computed_ts_statmech	required	1	Statmech.scientific_origin should be computed for this rubric.
statmech_present	computed_thermo	optional	1	Linked statmech evidence is expected when schema support exists.
statmech_treatment_present	computed_statmech	required	1	Statmech treatment kind should be recorded.
statmech_treatment_present	computed_ts_statmech	required	1	Statmech treatment kind should be recorded.
supporting_calculations_present	computed_transition_state	required	2	At least one calculation should support this TS entry.
supporting_geometry_source_present	computed_transport	optional	1	Computed transport should link supporting-geometry evidence when available.
temperature_range_present	computed_kinetics	optional	1	Both tmin_k and tmax_k should be populated.
temperature_range_present_if_applicable	computed_thermo	optional	1	Range-bearing thermo should declare temperature bounds.
temperature_range_valid	computed_kinetics	optional	1	Temperature range should satisfy 0 < tmin_k < tmax_k <= 10000.
temperature_range_valid	computed_thermo	optional	1	Temperature ranges should satisfy 0 < low < high <= 20000.
thermo_model_present	computed_thermo	required	1	Thermo should expose scalar, NASA-7, NASA-9, Wilhoit, or tabulated-point model evidence.
thermo_not_rejected_or_deprecated_if_applicable	computed_thermo	optional	1	Thermo rejection/deprecation checks apply once modeled.
thermo_origin_is_computed	computed_thermo	required	1	Thermo.scientific_origin should be computed for this rubric.
thermo_points_present	computed_thermo	optional	1	Tabulated thermo should include at least one point with a thermo value.
torsion_definitions_present	computed_statmech	optional	1	Recorded torsions should include torsion coordinate definitions.
torsion_definitions_present	computed_ts_statmech	optional	1	Recorded torsions should include torsion coordinate definitions.
torsion_symmetry_recorded	computed_statmech	optional	1	Recorded torsions should include symmetry numbers.
torsion_symmetry_recorded	computed_ts_statmech	optional	1	Recorded torsions should include symmetry numbers.
torsions_recorded_if_hindered_rotor_treatment	computed_statmech	optional	1	Hindered-rotor/statmech torsion treatments should include torsion rows.
torsions_recorded_if_hindered_rotor_treatment	computed_ts_statmech	optional	1	Hindered-rotor/statmech torsion treatments should include torsion rows.
transition_state_entry_present	computed_transition_state	required	1	The transition_state_entry record under evaluation is loaded.
transition_state_entry_present	computed_ts_statmech	required	1	Statmech must be attached to a transition_state_entry.
transition_state_parent_present	computed_transition_state	required	1	transition_state_entry must resolve to its parent transition_state.
transport_model_present	computed_transport	required	1	Transport should expose at least one structured property representation.
transport_not_rejected_or_deprecated_if_applicable	computed_transport	optional	1	Transport rejection/deprecation checks apply once modeled.
transport_origin_is_computed	computed_transport	required	1	Transport.scientific_origin should be computed for this rubric.
transport_property_present	computed_transport	required	1	At least one transport property must be populated.
ts_energy_source_present	computed_kinetics	optional	1	Computed TST kinetics should link a TS energy source calculation.
ts_frequency_present	computed_transition_state	optional	1	A frequency calculation should be in the source set.
ts_graph_or_smiles_present	computed_transition_state	optional	1	A SMILES or mol blob should be attached to the TS entry.
ts_optimization_present	computed_transition_state	optional	1	A TS-optimization calculation should be in the source set.
ts_single_point_present	computed_transition_state	optional	1	A single-point calculation should be in the source set.
ts_status_not_rejected	computed_transition_state	required	1	transition_state_entry.status must not be rejected.
ts_status_recorded	computed_transition_state	required	1	transition_state_entry.status must be set.
tunneling_metadata_present_if_claimed	computed_kinetics	optional	1	A claimed tunneling model should have a non-empty identifier.
uncertainty_present	computed_kinetics	optional	1	At least one uncertainty field should be populated.
uncertainty_present	computed_thermo	optional	1	At least one thermo uncertainty field should be populated.
uses_projected_frequencies_recorded	computed_statmech	optional	1	Projected-frequency handling should be explicitly recorded.
uses_projected_frequencies_recorded	computed_ts_statmech	optional	1	Projected-frequency handling should be explicitly recorded.
workflow_tool_release_present	computed_calculation	optional	1	Calculation should declare which workflow_tool_release orchestrated it.
workflow_tool_release_present	computed_kinetics	optional	1	Kinetics or at least one source calc should declare workflow-tool release metadata.

Which contract a response answers under

Read profile

On the wire: request.profile, echoed on every scientific response.

Which contract the response answers under. Always echoed, never inferred: a consumer should not have to guess whether they are looking at the archive or at a curated set.

Token	What it means
exploratory	Every visible candidate, each with its own review and trust state, and no recommendation from TCKDB about which is right. This is the default on every read surface, deliberately: on a corpus that is mostly uncurated a curated default returns an empty page and reads as a broken database.
curated	Only records at or above the approved review floor. Records are not annotated with any release selection that names them — for an attributed endorsement use the /api/v1/scientific/releases/* endpoints.

Profile recommendation

On the wire: request.profile_recommendation, echoed beside request.profile.

Whether the records in this response carry a TCKDB recommendation. It is a separate field from the profile because none of its three values can be derived from the profile token alone.

Token	What it means
none	These are candidates. TCKDB is not telling you which one to use.
approved_floor_only	Every record shown is at or above the approved review floor and nothing more is claimed. A human accepted each of them, which is not the same as TCKDB preferring them over their siblings.
tckdb_curated_release	These records are the ones an attributed, append-only release selection names in a published release. Only the release endpoints emit this.

Dataset release status

On the wire: status on a dataset release.

Lifecycle of a citable dataset release.

Token	What it means
draft	Being assembled. Selections may still be appended, no manifest is frozen, and it is neither served under the curated profile nor citable.
published	The manifest is frozen and checksummed. The release is citable and its bytes are reproducible.
withdrawn	It was published and later retracted. The row and its manifest are kept so an existing citation never dangles; the status is how a consumer is told not to rely on it.

Release selection action

On the wire: action on a release selection row.

What one selection row asserts. Selections are append-only and never edited: a curator changing their mind appends a row pointing at the one it replaces.

Token	What it means
select	The first attributed selection of a candidate record.
supersede	Replaces an earlier selection with a different candidate.
withdraw	Retires an earlier selection with no replacement — the release then makes no recommendation for that subject.

Release artifact kind

On the wire: kind on a file listed in a release manifest.

The role of one checksummed file inside a dataset release. A release deliberately ships the selection and the material needed to disagree with it.

Token	What it means
selected_records	The records the release selects.
candidate_records	The candidates that were not selected, so a reader can check the choice.
review_history	The review decisions behind those records.
selection_ledger	The append-only log of selection actions themselves.

How your query matched

Reaction direction

On the wire: the direction request parameter, and — the one that surprises people — matched_direction on every reaction and kinetics search result.

Which way round the stored equation had to be read for your query to match it. TCKDB stores a reaction in one orientation; a query naming the other side still matches, and matched_direction is how the response tells you that happened. It is present on every row, including the forward ones, so its absence never has to be interpreted.

Token	What it means
forward	Your query matched the reaction as stored: what you asked for as reactants are that reaction's reactants.
reverse	Your query matched the reaction read backwards: what you asked for as reactants are that reaction's products.
either	Match the reaction in whichever orientation works. This is the default on a request; it is not an answer a result row gives — a matched row always reports forward or reverse.

Search reactants=NN and one of the results is [NH2] + [NH2] <=> NN with matched_direction: "reverse". Nothing is wrong: NN is stored as a product of that reaction, and reading the equation backwards puts it on the reactant side, which is what your query asked about. What matched_direction does not tell you is which way round the rate coefficients on that record run: a kinetics record carries its own direction (below), stated relative to the stored orientation. So read both — matched_direction says how TCKDB found the reaction for you, direction says what the numbers on it describe.

Kinetics direction

On the wire: direction on a kinetics record, and the filter of the same name.

Which direction of the stored equation a rate coefficient describes. It is stated relative to the reaction entry's stored reactant-to-product orientation, which is what makes it a different question from matched_direction: that one is about your query, this one is about the numbers. A record may leave it unset — the historical default — in which case the value comes back empty and all you know is that the producer did not say.

Token	What it means
forward	A fit of the rate in the stored orientation: reactants to products as written.
reverse	A fit of the rate for the same equation run backwards. It can sit on the same reaction entry as a forward fit — Chemkin and Cantera give the two as separate expressions, so TCKDB keeps them as separate records rather than merging them.
net	A rate that already folds both directions together — an apparent or observed net rate.

Participant match mode

On the wire: the match request parameter on reaction and kinetics search.

How the species you listed are compared against a stored reaction's sides.

Token	What it means
contains	The default. Set containment per role: every species you name must appear in that role of the stored reaction, and a side you did not mention constrains nothing. Containment is by set, not multiset — naming a species once matches a reaction consuming two of it. For example: reactants=NN alone means "NN among the reactants, products unconstrained" — which is what a chemist means by "reactions of hydrazine".
exact	Multiset equality on both sides: precisely this equation, both sides, counts included. Ask for this when you want one specific reaction rather than a family.

Selection policy

On the wire: the policy field of a .../select request.

Which record is listed first among the eligible ones a select endpoint reports. Naming the policy makes "show me one" an explicit choice rather than a silent one; a browse read has no such parameter and never picks. No policy persists a curator decision — for an attributed endorsement, use a dataset release.

Token	What it means
default	The endpoint's display order: review rank, then newest deposited.
latest	Most recently deposited first.
most_reviewed	Review rank first (approved, then under_review and not_reviewed together), then most recently deposited.

Structure search mode

On the wire: the mode request parameter on structure search, echoed in each match summary.

Which matching algorithm produced a structure-search hit.

Token	What it means
substructure	RDKit substructure containment: the stored molecule contains the query pattern.
similarity	Tanimoto similarity over Morgan fingerprints. Only this mode populates similarity_score on a result.
exact	Equality of canonical InChIKey.

Structure query kind

On the wire: matched_query_kind on a structure-search match summary.

Which of the query fields a hit came from, echoed so a caller with several query inputs can attribute a result without re-parsing the request.

Token	What it means
smiles	The match came from the supplied SMILES.
smarts	The match came from the supplied SMARTS pattern.
inchi	The match came from the supplied InChI.
inchi_key	The match came from the supplied InChIKey.

How a record was produced

Scientific origin

On the wire: scientific_origin on a record, and the filter of the same name.

Where a number came from, before anything else is said about it.

Token	What it means
computed	Produced by a quantum-chemistry or kinetics calculation.
experimental	Measured in a laboratory rather than computed or estimated.
estimated	Estimated — group additivity, an analogy, a correlation.

Calculation type

On the wire: calculation_type on a calculation record, and the filter of the same name.

What kind of job a stored calculation was. TCKDB records the job, not the intent: a freq on an unoptimised geometry is still a freq.

Token	What it means
opt	Geometry optimisation.
freq	Frequency (Hessian) calculation.
sp	Single-point energy.
irc	Intrinsic reaction coordinate following.
scan	A scan over one or more internal coordinates.
path_search	A reaction-path search producing a TS guess. Which algorithm ran (NEB, GSM, …) is recorded on the result row, not as a separate type.
conf	A conformer search — a job exploring the accessible conformations of one species.
composite	One composite energy: a named method such as CBS-QB3 or G4 that one program run produced from several internal steps. Its energies are on the result row, and its level of theory is bound to a composite scheme.

Calculation quality

On the wire: quality on a calculation record, and the filter of the same name.

A curation flag on one calculation, separate from the review status of the record it supports.

Token	What it means
raw	The default every calculation is stored with. It means nobody has curated it, not that anything is wrong.
curated	Someone has curated this calculation and stands behind it.
rejected	Marked unusable. Such calculations are excluded from results unless a request opts in with include_rejected_quality=true, and a record resting on one is hard-failed with calculation_rejected.

Legacy composite shape

On the wire: levels.legacy_composite_shape on a record, and the same field on a calculation.

A way of depositing a composite energy from before TCKDB had a composite calculation type. It is an annotation only: the record reads exactly as it was deposited, and its levels are derived as they always were.

Token	What it means
composite_role_on_non_composite_calculation	A calculation that is not of type composite (a single point, say) is linked to the record under the source role composite.
named_method_level_on_non_composite_calculation	An optimisation, frequency or single-point calculation ran at the level of a named composite method such as CBS-QB3. The energy of such a method is one number a program printed after several internal steps, which a composite calculation records and a plain single point cannot.

Composite term linearity

On the wire: linearity on each term of a composite scheme read.

Whether one term of a composite recipe is a fixed linear combination of the energies of its inputs, so that each input's coefficient means something. Derived from the term's operation and formula; never stored.

Token	What it means
linear	A value, base or difference term, or a two-point extrapolation. Each input carries its coefficient: +1 for a value, +1 and -1 for the high and low of a difference, and the closed-form weights of the extrapolation (which sum to 1).
nonlinear	The three-point exponential extrapolation. Its limit is a ratio of differences of the energies, so it has no fixed weights, and none are given.
not_applicable	An empirical term, which is not computed from inputs at all.

Geometry validation status

On the wire: validation_status on a calculation's geometry-validation summary, and geometry_validation_status on a calculation evidence summary.

What TCKDB found when it compared a calculation's geometry against the structure the record claims it is — connectivity and molecular identity, not energetics.

Token	What it means
passed	The geometry is the structure the record claims.
warning	Something differs and TCKDB will not call it a failure. An optimisation that drifted is science to record, not a payload to refuse.
fail	The automated comparison found a mismatch. It is a curator-attention signal, not proof the geometry is wrong, and it does not hard-fail the calculation's trust badge: it is reported as a warning on the geometry check.
not_present	Nobody checked. There is no validation row for this calculation, and the read layer says so rather than leaving the field empty — an absent check and a passed check are different answers and TCKDB will not let them look alike.

The record itself stores only passed, warning, fail; not_present is added by the read layer, which is why you will not find it in the database schema.

Atom-map source

On the wire: source on a reaction's atom-map badge.

How the atom-to-atom correspondence across a reaction was obtained. The column has no default: a map that cannot say how it was obtained is not a map TCKDB accepts.

Token	What it means
declared	A depositor stated the correspondence — they ran the calculation and followed the reaction coordinate, so they know which atom went where.
inferred	An algorithm produced it. Read back as inferred, never as though a human asserted it.

Transition-state entry status

On the wire: status on a transition-state entry.

How far a transition-state entry has been taken by whoever deposited it.

Token	What it means
guess	A starting structure. Not optimised.
optimized	Optimised to a stationary point.
validated	Optimised and checked as a transition state for the reaction it claims — the strongest thing an entry says about itself.
rejected	Kept, but not to be used. It hard-fails the entry's trust badge with ts_entry_status_rejected.

Artifact integrity finding

On the wire: finding on an artifact-integrity observation.

What was observed when TCKDB read stored bytes back and checked them against their digest. Not severities: four different observations, and the log is append-only, so a repaired object is a new observation rather than an edit.

Token	What it means
digest_mismatch	The object was read and does not hash to the key it is stored under. The bytes are not the bytes TCKDB claims to hold.
size_mismatch	The digest could not be faulted but the length differs from the byte count on the artifact row — almost always a truncated read rather than a changed object.
object_missing	The object is absent from the store entirely.
verified	The object was read and does hash to its key. Recorded only for a digest that already carries a break — this is the observation that clears one, which is why a restored record does not stay condemned forever.

Why a request was refused

When TCKDB refuses a request the body carries a code. Branch on that, never on the English detail — the code is the contract and the sentence is not. These are every code a caller can receive; the catalogue also holds codes for internal guards and server faults, which no request can provoke and which are therefore not listed here.

Two facts accompany each one, and neither is obvious from the name:

• A thing or a relationship. A code naming a thing (unknown_release, smiles_too_long) is complete as it stands. A code naming a relationship (state_conflict, a mismatch, an ambiguity) asserts something about two or more things and names none of them, so the envelope's structured context owes you which ones. Where a context is still empty for such a code, that is a known gap rather than a claim that there is nothing to say.
• Whether replaying helps. Every code here refuses something about the request, so replaying an unchanged request generally meets the same answer. The exception worth knowing is the short list at the end of this section: server-side conditions a retry layer must not replay, because they are deterministic and no wait will clear them.

There is deliberately no definition column: the refusal already sent you a sentence, and a second copy kept here would drift from it. backend/app/api/code_catalogue.py names the module that raises each one.

HTTP 400 (1 code)

Code	Names
invalid_idempotency_key	a thing

HTTP 403 (3 codes)

Code	Names
rights_attestation_not_depositor	a thing
rights_attestation_requires_curator	a thing
submission_supersede_not_owner	a thing

HTTP 404 (28 codes)

Code	Names
curator_task_not_found	a thing
handle_not_found	a thing
hessian_not_found	a thing
irc_result_not_found	a thing
manifest_not_frozen	a thing
owner_missing	a thing
path_search_result_not_found	a thing
scan_result_not_found	a thing
structure_finding_reference_not_found	a thing
structure_finding_subject_not_found	a thing
unknown_calculation_artifact_ref	a thing
unknown_calculation_ref	a thing
unknown_conformer_group_ref	a thing
unknown_conformer_selection	a thing
unknown_curation_policy	a thing
unknown_kinetics_determination_ref	a thing
unknown_network_channel	a thing
unknown_network_kinetics_ref	a thing
unknown_network_solve_ref	a thing
unknown_record	a thing
unknown_release	a thing
unknown_release_artifact	a thing
unknown_selection	a thing
unknown_statmech_candidate_ref	a thing
unknown_statmech_ref	a thing
unknown_structure_determination_ref	a thing
unknown_structure_member_ref	a thing
unknown_transition_state_entry_ref	a thing

HTTP 409 (26 codes)

Code	Names
atom_map_element_not_conserved	a relationship — read context
atom_map_not_a_bijection	a relationship — read context
curation_policy_version_conflict	a relationship — read context
doi_already_recorded	a relationship — read context
email_taken	a thing
energy_correction_scheme_identity_conflict	a relationship — read context
energy_correction_scheme_literature_already_set	a thing
energy_correction_scheme_software_already_set	a thing
energy_correction_scheme_workflow_tool_release_already_set	a thing
energy_transfer_scope_columns_disagree	a relationship — read context
idempotency_conflict	a relationship — read context
last_admin_demotion	a thing
manifest_already_frozen	a thing
network_solve_reported_requires_literature	a thing
reference_conflict	a relationship — read context
release_not_draft	a thing
release_not_published	a thing
release_tag_taken	a thing
selection_already_stands	a relationship — read context
selection_already_superseded	a relationship — read context
state_conflict	a relationship — read context
statmech_subject_not_exactly_one	a thing
superseded_record_not_approvable	a relationship — read context
unique_conflict	a relationship — read context
unknown_manifest_schema	a thing
username_taken	a thing

HTTP 413 (2 codes)

Code	Names
bundle_too_large	a relationship — read context
network_export_body_too_large	a relationship — read context

HTTP 422 (270 codes)

Code	Names
ambiguous_conformer_selection_locator	a relationship — read context
applied_energy_correction_source_calculation_owner_mismatch	a relationship — read context
applied_energy_correction_source_key_undeclared	a thing
arrhenius_a_units_molecularity_mismatch	a relationship — read context
atom_map_atoms_unaccounted_for	a relationship — read context
atom_map_contradicts_irc_mapping	a relationship — read context
atom_map_element_not_conserved	a relationship — read context
atom_map_geometry_unparseable	a thing
atom_map_indices_not_geometry_relative	a relationship — read context
atom_map_inferred_requires_note	a thing
atom_map_not_a_bijection	a relationship — read context
atom_map_participant_not_declared	a thing
atom_map_without_transition_state	a thing
bac_total_requires_components	a relationship — read context
browse_parameter_removed	a relationship — read context
bundle_too_many_records	a relationship — read context
calculation_geometry_composition_mismatch	a relationship — read context
calculation_geometry_conformer_mismatch	a relationship — read context
calculation_geometry_isotope_mismatch	a relationship — read context
calculation_handle_conflict	a relationship — read context
calculation_input_geometry_mismatch	a relationship — read context
calculation_key_undeclared	a thing
calculation_software_is_workflow_tool	a thing
calculation_software_release_required	a thing
candidate_rights_basis_incompatible	a relationship — read context
candidate_rights_basis_missing	a relationship — read context
canonical_parameter_value_requires_key	a thing
client_sort_not_supported	a thing
composed_search_candidate_limit_exceeded	a relationship — read context
composed_search_invalid_page	a relationship — read context
composed_search_pagination_changed	a relationship — read context
composed_search_pagination_stalled	a relationship — read context
composite_assembled_cannot_be_primary	a thing
composite_assembled_not_accepted	a thing
composite_e0_inconsistent	a relationship — read context
composite_input_duplicate	a relationship — read context
composite_input_edge_is_derived	a thing
composite_input_geometry_mismatch	a relationship — read context
composite_input_level_mismatch	a relationship — read context
composite_input_missing	a thing
composite_input_owner_mismatch	a relationship — read context
composite_input_reference_invalid	a thing
composite_input_slot_unknown	a relationship — read context
composite_input_type_invalid	a relationship — read context
composite_inputs_require_assembled	a thing
composite_level_not_scheme_bound	a thing
composite_program_run_requires_software	a thing
composite_result_requires_composite_type	a thing
composite_scheme_malformed	a relationship — read context
composite_scheme_named_method_not_sendable	a thing
composite_scheme_nested	a relationship — read context
composite_term_position_unknown	a relationship — read context
composite_terms_do_not_sum	a relationship — read context
composite_total_mismatch	a relationship — read context
composite_total_required	a thing
composite_type_requires_composite_result	a thing
conformer_key_undeclared	a thing
cursor_offset_conflict	a relationship — read context
cursor_query_mismatch	a relationship — read context
energy_correction_scheme_frequency_level_not_applicable	a relationship — read context
energy_correction_scheme_frequency_level_without_energy_level	a relationship — read context
enthalpy_declaration_absent	a relationship — read context
enthalpy_declaration_without_content	a relationship — read context
enthalpy_quantity_not_storable_here	a relationship — read context
enthalpy_reference_kind_unrecognized	a relationship — read context
export_all_cap_exceeded	a relationship — read context
export_ref_unmatched	a relationship — read context
export_seed_empty	a thing
export_seed_unresolved	a thing
export_selection_ambiguous	a relationship — read context
freq_list_exceeds_geometry_degrees_of_freedom	a relationship — read context
freq_mode_index_not_unique	a relationship — read context
freq_n_imag_disagrees_with_modes	a relationship — read context
geometry_isotope_symbol_conflict	a relationship — read context
geometry_key_unresolved	a thing
geometry_too_large	a relationship — read context
handle_type_mismatch	a relationship — read context
include_not_implemented_yet	a thing
invalid_cursor	a thing
invalid_handle	a thing
invalid_pagination	a thing
invalid_property_kind	a thing
invalid_range	a relationship — read context
invalid_structure_query	a thing
invalid_temperature_range	a relationship — read context
kinetics_declaration_contradicts_record	a relationship — read context
kinetics_declaration_invalid	a thing
kinetics_declaration_version_unsupported	a thing
kinetics_determination_invalid	a relationship — read context
kinetics_determination_mismatch	a relationship — read context
kinetics_energy_level_contradiction	a relationship — read context
kinetics_interpretation_conformer_selection_owner_mismatch	a relationship — read context
kinetics_interpretation_statmech_owner_mismatch	a relationship — read context
kinetics_protocol_calculation_owner_mismatch	a relationship — read context
kinetics_selection_population_too_large	a thing
level_of_theory_handle_conflict	a relationship — read context
level_of_theory_method_is_compound	a thing
level_of_theory_method_with_composite_scheme	a relationship — read context
level_of_theory_requires_method_or_composite_scheme	a thing
limit_too_large	a relationship — read context
lowest_energy_unavailable	a thing
micro_reaction_key_undeclared	a thing
missing_filter	a thing
missing_identifier	a thing
missing_reaction_search_filter	a thing
missing_structure_query	a thing
missing_version_parent	a thing
ml_export_all_cap_exceeded	a relationship — read context
ml_export_lot_unresolved	a thing
ml_export_seed_empty	a thing
ml_export_seed_unresolved	a thing
multiple_structure_queries	a relationship — read context
n_imag_contradicts_minimum	a relationship — read context
network_channel_key_undeclared	a thing
network_declaration_invalid	a relationship — read context
network_declaration_version_unsupported	a thing
network_energy_source_subject_mismatch	a relationship — read context
network_energy_source_type_mismatch	a relationship — read context
network_export_choice_not_allowed	a relationship — read context
network_export_manifest_invalid	a relationship — read context
network_export_manifest_stale	a relationship — read context
network_export_representation_choice_invalid	a relationship — read context
network_export_unsupported_form	a relationship — read context
network_kinetics_batch_evaluate_grid_too_large	a relationship — read context
network_kinetics_evaluate_grid_too_large	a relationship — read context
network_kinetics_evaluate_invalid_point	a thing
network_kinetics_evaluate_missing_pressure	a thing
network_kinetics_evaluate_missing_temperature	a thing
network_kinetics_evaluate_model_kind_not_supported	a thing
network_kinetics_rate_units_missing	a thing
network_selection_population_too_large	a relationship — read context
network_selection_snapshot_too_large	a relationship — read context
network_state_energy_sum_mismatch	a relationship — read context
network_state_key_undeclared	a thing
non_finite_value	a thing
observation_identity_already_set	a thing
observation_identity_attach_requires_submission	a relationship — read context
observation_identity_hint_conflict	a relationship — read context
observation_identity_target_not_ground_state_minimum	a relationship — read context
offset_too_large	a relationship — read context
parameter_renamed	a relationship — read context
parameter_value_requires_key	a thing
post_search_fields_must_be_in_body	a thing
pressure_alias_conflict	a relationship — read context
query_too_expensive	a relationship — read context
rationale_required	a thing
reaction_charge_not_conserved	a relationship — read context
reaction_entry_handle_conflict	a relationship — read context
reaction_handle_conflict	a relationship — read context
reaction_mass_balance_failed	a relationship — read context
reaction_reversible_required	a thing
record_has_no_subject	a thing
record_not_approved	a thing
record_ref_not_selectable	a thing
record_subject_mismatch	a relationship — read context
record_type_not_selectable	a thing
relative_conformer_energy_compare_identical_protocols	a relationship — read context
relative_conformer_energy_population_too_large	a relationship — read context
relative_conformer_energy_scope_owner_mismatch	a relationship — read context
relative_conformer_energy_unsupported	a relationship — read context
release_scoping_not_implemented	a thing
release_selects_nothing	a thing
rights_basis_incompatible	a relationship — read context
rights_basis_missing	a relationship — read context
rights_license_blank	a thing
rights_source_terms_required	a thing
scf_stability_source_calculation_owner_mismatch	a relationship — read context
scf_stability_source_conformer_unanchored	a relationship — read context
scf_stability_source_cycle	a relationship — read context
scf_stability_source_geometry_mismatch	a relationship — read context
selection_no_longer_approved	a thing
smiles_too_long	a relationship — read context
sp_energy_component_derived	a thing
sp_energy_component_duplicate	a thing
sp_energy_component_not_on_sp	a thing
sp_energy_component_total_mismatch	a relationship — read context
sp_energy_components_do_not_sum	a relationship — read context
sp_energy_components_require_energy	a thing
species_entry_handle_conflict	a relationship — read context
species_geometry_composition_mismatch	a relationship — read context
species_geometry_isotope_mismatch	a relationship — read context
species_handle_conflict	a relationship — read context
species_key_undeclared	a thing
species_kind_conflict	a relationship — read context
species_smiles_charge_mismatch	a relationship — read context
statmech_calculation_key_undeclared	a thing
statmech_energy_level_ambiguous	a relationship — read context
statmech_energy_level_contradiction	a relationship — read context
statmech_energy_level_requires_sp	a relationship — read context
statmech_energy_sp_and_composite_linked	a relationship — read context
statmech_model_declaration_invalid	a thing
statmech_model_declaration_mismatch	a relationship — read context
statmech_model_declaration_version_unsupported	a thing
statmech_role_duplicate	a relationship — read context
statmech_selection_bound_exceeded	a relationship — read context
statmech_selection_scope_owner_mismatch	a relationship — read context
statmech_selection_unsupported	a relationship — read context
statmech_source_calculation_owner_mismatch	a relationship — read context
statmech_source_role_type_mismatch	a relationship — read context
statmech_sp_geometry_mismatch	a relationship — read context
statmech_torsion_scan_calculation_owner_mismatch	a relationship — read context
stored_species_smiles_unparseable	a thing
structure_declaration_invalid	a thing
structure_declaration_version_unsupported	a thing
structure_determination_invalid	a relationship — read context
structure_determination_mismatch	a relationship — read context
structure_finding_adjudication_needs_target	a thing
structure_finding_already_settled	a relationship — read context
structure_finding_correction_needs_adjudication	a thing
structure_finding_correction_subject_mismatch	a relationship — read context
structure_finding_dismissal_needs_target	a thing
structure_finding_literature_unidentified	a thing
structure_finding_rationale_required	a thing
structure_finding_reference_invalid	a thing
structure_finding_role_mismatch	a relationship — read context
structure_finding_scope_subject_mismatch	a relationship — read context
structure_selection_evidence_too_large	a relationship — read context
structure_selection_manifest_too_large	a relationship — read context
structure_selection_population_too_large	a relationship — read context
structure_selection_traversal_too_deep	a relationship — read context
structure_selection_unsupported	a relationship — read context
subject_type_mismatch	a relationship — read context
supersedes_same_record	a relationship — read context
thermo_declaration_invalid	a thing
thermo_energy_level_ambiguous	a relationship — read context
thermo_energy_level_contradiction	a relationship — read context
thermo_energy_level_requires_sp	a relationship — read context
thermo_energy_sp_and_composite_linked	a relationship — read context
thermo_protocol_calculation_owner_mismatch	a relationship — read context
thermo_protocol_version_unsupported	a thing
thermo_recipe_name_listed	a thing
thermo_role_duplicate	a relationship — read context
thermo_selection_condition_conflict	a relationship — read context
thermo_selection_population_too_large	a relationship — read context
thermo_source_calculation_owner_mismatch	a relationship — read context
thermo_source_role_type_mismatch	a relationship — read context
thermo_sp_geometry_mismatch	a relationship — read context
thermo_statmech_owner_mismatch	a relationship — read context
thermo_target_group_not_allowed	a relationship — read context
thermo_target_group_owner_mismatch	a relationship — read context
thermo_target_group_required	a relationship — read context
thermoml_doi_conflict	a relationship — read context
thermoml_file_too_large	a relationship — read context
thermoml_invalid_base64	a thing
thermoml_no_supported_content	a relationship — read context
thermoml_schema_invalid	a thing
too_many_element_symbols	a relationship — read context
transition_state_calculation_conformer_key	a relationship — read context
transition_state_calculation_species_geometry	a relationship — read context
transition_state_charge_mismatch	a relationship — read context
transition_state_composition_mismatch	a relationship — read context
transition_state_irc_mapping_element_mismatch	a relationship — read context
transition_state_key_undeclared	a thing
transition_state_no_imaginary_mode	a thing
transition_state_reaction_coordinate_ambiguous	a relationship — read context
transition_state_reaction_coordinate_not_designated	a thing
transport_source_calculation_owner_mismatch	a relationship — read context
ts_energy_ordering_source_type_mismatch	a relationship — read context
ts_energy_ordering_stated_energy_mismatch	a relationship — read context
unknown_element_symbol	a thing
unknown_include_token	a thing
unknown_query_parameter	a thing
unknown_record_type	a thing
unsafe_lowest_energy_comparison	a thing
unsupported_direction	a thing
unsupported_filter	a thing
unsupported_ranking_for_calculation_type	a thing
unsupported_reaction_molecularity	a thing
unsupported_release_record_type	a thing
withdraw_reason_required	a thing

HTTP 426 (3 codes)

Code	Names
tckdb_client_version_invalid	a thing
tckdb_client_version_missing	a thing
tckdb_client_version_unsupported	a relationship — read context

HTTP 429 (1 code)

Code	Names
rate_limit_exceeded	a thing

Codes it is pointless to replay (2)

These arrive at a status that normally invites a retry, and for these codes a retry is a loop with no exit: the condition is deterministic, so waiting cannot clear it and only an operator can. They refuse nothing you did, which is why they are absent from the tables above. The same list is generated into the Python client as NON_RETRYABLE_CODES; backend/app/api/code_catalogue.py records why each one is permanent.

• artifact_integrity_failed — HTTP 502
• artifact_object_missing — HTTP 502

---

Tokens are read from the code at generation time; the definitions live in backend/app/glossary/declarations.py, beside the enum each one describes. backend/tests/scripts/test_api_vocabulary.py holds this document to its sources: it fails if the committed copy drifts from a fresh render, if a declared token is not a real member of its enum, or if an enum every response carries has no entry here.