Struct MailFathomErrorCode
- Namespace
- MailFathom.Domain.Failures
- Assembly
- MailFathom.Domain.dll
Identifies a failure MailFathom raised deliberately, as a five-digit code stable enough to publish.
[JsonConverter(typeof(MailFathomErrorCodeJsonConverter))]
public readonly record struct MailFathomErrorCode : IEquatable<MailFathomErrorCode>- Implements
- Inherited Members
Remarks
The type is a closed enumeration of values rather than a C# enum, because the number is the identity: it is what a log records, what an alert matches, and what a support conversation names. An enum member's ordinal would carry no meaning outside this assembly, and its name would change with every rename of the failure it belongs to.
The code reads as C S NNN: the first digit is the Category, the second is the
Subcategory within it, and the last three number the failure inside that subcategory. A reader who
sees 21001 knows it is a mail-protocol failure about authentication before looking anything up.
Numbers are allocated once and never reused or renumbered, for the same reason an enum member's value is never reordered: a code that changes meaning silently invalidates every runbook, alert, and log search written against it. Being a struct, default is reachable and names no failure; IsSpecified reports that, and every failure reaches its code through a declared member, so the default cannot arrive from a raised exception.
The cost against an enum is that the members are not compile-time constants, so a boundary translates them through a lookup rather than through a switch over constants.
Properties
- All
Gets every allocated code.
- Category
Gets the subsystem the failure belongs to, which is the code's first digit.
- DatabaseSchemaOutOfDate
Gets subcategory 2, schema state: the database does not carry every migration the running build was compiled against.
- DatabaseSchemaStateUnreadable
Gets subcategory 2, schema state: the migration history could not be read, so the schema is of unknown shape.
- DatabaseSchemaTextSearchConfigurationMismatch
Gets subcategory 2, schema state: the lexical index was built with a different text search configuration than the one configured.
- EmailContentReadCountOutOfRange
Gets subcategory 1, request validation: a content read named no emails, or more emails than one call serves.
- EmailContentReadDuplicateEmail
Gets subcategory 1, request validation: a content read named the same email more than once.
- EmailContentUnavailable
Gets subcategory 5, local consistency: an email exists locally, but the content stored for it is missing, damaged, or unreadable.
- EmailSearchResultLimitOutOfRange
Gets subcategory 1, request validation: an email search asked for more ranked results than the search serves.
- EmbeddingProviderCredentialRejected
Gets subcategory 1, credentials: an embedding provider refused the credential this deployment presented.
- EmbeddingProviderUnavailable
Gets subcategory 2, availability: no endpoint of the declared chain served an embedding request within the budget configured for it.
- EmbeddingVectorIndexUnavailable
Gets subcategory 3, vector indexes: the approximate index one embedding profile's vectors are searched through is not in the state its lifecycle asked for.
- EmbeddingVectorShapeUnexpected
Gets subcategory 3, answer shape: a provider returned a vector the declared geometry does not describe.
- EnvironmentOnlySettingMisplaced
Gets subcategory 2, configuration sources: a setting only the process environment can deliver carries a value that came from somewhere else.
- IsSpecified
Gets whether this value names an allocated code rather than the unusable struct default.
- MailAccessTokenUnavailable
Gets subcategory 3, mailbox access tokens: an account's authorization server did not issue an access token its OAuth mechanisms require.
- MailAccountNotAccessible
Gets subcategory 3, access: a request named a mail account this deployment does not serve.
- MailAuthenticationMechanismUnavailable
Gets subcategory 1, authentication: a mail server advertises no authentication mechanism the account's policy permits.
- MailTransportSecurityPolicyViolated
Gets subcategory 1, transport security policy: a configured combination would weaken protection in a way no opt-in allows.
- MailboxAnswerIncomplete
Gets subcategory 4, answer completeness: a mail server answered for an email without the data items the command requested.
- MailboxAuthorizationFailed
Gets subcategory 3, mailbox access tokens: an operator-driven authorization run did not produce a refresh token to provision.
- MailboxFolderRecreated
Gets subcategory 3, folder identity: a folder was reselected with a UIDVALIDITY that makes the session's identities name different emails.
- MailboxMutationAttemptsExhausted
Gets subcategory 5, mutation support: a mutation spent its bounded attempts without completing.
- MailboxMutationDestinationMissing
Gets subcategory 5, mutation support: the folder a relocation or a copy names as its destination does not exist on the server.
- MailboxMutationFailedUnexpectedly
Gets subcategory 5, mutation support: a mutation ended in a failure this system does not classify.
- MailboxMutationOutcomeUnknown
Gets subcategory 5, mutation support: a command that must never be issued twice went out and its answer never came back.
- MailboxMutationUnsupported
Gets subcategory 5, mutation support: a mail server advertises no extension able to carry a requested change safely.
- MailboxQueryCursorFilterMismatch
Gets subcategory 2, pagination: a continuation cursor was issued for a different set of filters than the request carries.
- MailboxQueryCursorMalformed
Gets subcategory 2, pagination: a continuation cursor is not one this system issued.
- MailboxQueryFilterInvalid
Gets subcategory 1, request validation: one filter of a mailbox query carries a value, a count, or a length the query does not accept.
- MailboxQueryPageSizeOutOfRange
Gets subcategory 1, request validation: a mailbox query asked for a page size outside the range the query serves.
- MailboxUnavailable
Gets subcategory 2, session availability: a mail server did not serve an operation within the resilience budget configured for it.
- McpToolFailedUnexpectedly
Gets subcategory 4, undiagnosed failure: a tool call failed for a reason the boundary deliberately does not describe.
- OutboundDependencyUnavailable
Gets subcategory 1, pipeline rejection: a resilience pipeline declined to serve an operation against an outbound dependency any further.
- PersistenceConcurrencyConflict
Gets subcategory 1, concurrent writes: a local write did not commit because another writer changed the same durable state.
- ProvisionedConfigurationSourceInvalid
Gets subcategory 2, configuration sources: the deployment's configuration-source settings name a path that is absent or a setting that does not exist.
- StoredEmailIdentifierMalformed
Gets subcategory 1, request validation: a request named an email by text that is not an identifier this system issues.
- StoredEmailNotFound
Gets subcategory 3, access: a request named an email the local mailbox copy holds no row for.
- Subcategory
Gets the concern within the category, which is the code's second digit.
- Value
Gets the five-digit code.
Methods
- ToString()
Returns the five-digit code, so a log or an error response records the number rather than the structure.
- TryParse(int, out MailFathomErrorCode)
Parses a recorded five-digit code back into the value it names.