Error Codes ​

These are the error codes shared by every service library DAT officially supports.

Each code carries two values — impact and retry — and some also carry a suspect tag.

Impact — the damage to the service ​

This is the basis for alerting. It answers one question: "Is the service down right now?"

No impact is not something to alert on. If every engineer on call has to look at a single piece of bad input, the alert stops meaning anything.

Suspect — investigate when it persists ​

A code tagged Suspect is part of normal operation when it happens once. A client can send a bad value at any time, and filtering it out is exactly the library's job.

But if such errors show up continuously, or in bursts from one source, it is one of two things.

• A configuration problem — a bad deployment, an old client still running, or certificates that no longer line up.
• An attack attempt — someone tampering with tokens or keys to get past verification, or probing for values that work.

So for these codes, track the count as a metric. Alert only when it crosses a threshold.

Retry ​

Token ​

Problems with the received token string itself.

Certificate ​

The format of the certificate string, and whether that certificate is usable right now.

DAT_CERT_NOT_FOUND and DAT_CERT_NOT_SYNCED look the same from outside but call for different responses. The first is a cid we never issued, so waiting will not produce it; the second clears as soon as synchronization catches up.

A single DAT_CERT_NOT_FOUND just gets filtered out, but a sudden increase means the deployment has drifted or forged tokens are circulating.

Signature ​

Encryption ​

Problems encrypting and decrypting the secure payload.

An empty secure payload is not an error. Empty input yields empty output and produces no code at all.

On the path that skips signature verification, the GCM tag is the only integrity check. That is why DAT_CRYPTO_TAG_MISMATCH is not folded into the same code as other decryption failures.

Key ​

Three that look alike but are not:

Manager ​

The state of the object that holds certificates and uses them to issue and verify.

The cause of DAT_MANAGER_NO_ISSUABLE_CERTIFICATE is one of four. Each one calls for something completely different.

If an issuing server is configured to receive only verify-only certificates, DAT_CERT_VERIFY_ONLY is what comes out. Waiting will never clear it, so it is not a retry case.

Configuration ​

Problems with the values the caller passed in. Every CONFIG code is an error that requires a code fix; seeing one in production means the deployment is wrong.

Internal ​

Problems with the execution environment and the runtime.

DAT_INTERNAL_UNAVAILABLE is fixed by correcting the deployment environment, while DAT_INTERNAL_UNKNOWN is usually a runtime fault or a library bug.

CMS Sync ​

These codes never appear if CMS synchronization is not used.

The codes that mark synchronization as a permanent failure (UNAUTHORIZED, FORBIDDEN, ENDPOINT_NOT_FOUND, MALFORMED, IMPORT_FAILED) are all critical. Retrying will not clear them while certificates keep expiring, so leaving them alone guarantees the service will stop.

UNREACHABLE and SERVER_ERROR, by contrast, are partial. The existing certificates keep working and the next cycle usually recovers — though repeated failure eventually escalates to critical. Alert on the number of consecutive failures.

Server ​

Codes produced by the CMS server. Clients never produce these; they only receive them.

Response envelope:

{
  "code": "DAT_REQ_ALG_UNSUPPORTED",
  "details": { "algorithm": "BOGUS-ALG" }
}

For errors that arise while creating and handling certificates, the server uses the same common codes as above (DAT_CERT_*, DAT_KEY_*, DAT_CONFIG_*).

When a server code arrives ​

The client wraps the server code in its own CMS code and preserves the original in cause.

Finding it by symptom ​

Appendix ​

Code syntax ​

DAT_<area>_<reason>

• When the same reason arises in different areas, the reason name is the same. DAT_TOKEN_MALFORMED and DAT_CERT_MALFORMED differ only in their subject; the meaning is identical.
• _UNKNOWN is reserved for the fallback in each area. It is never used to mean "unknown algorithm" or the like — that is _UNSUPPORTED.
• The code string is a public contract. Messages may change freely, but codes do not.

How each client exposes it ​

security event returns true only for the two cases where forgery or tampering is certain (DAT_SIG_MISMATCH, DAT_CRYPTO_TAG_MISMATCH). The suspect tag in this document covers a wider range — tampered tokens, keys, and requests as well — and for now it is a documentation classification only, not exposed through the client API.

The impact grade is likewise a documentation classification, because the same code hits differently depending on where it arose — DAT_KEY_INVALID has no impact when it filters an incoming token, but if it comes up while reading certificates during CMS synchronization, the whole synchronization fails.

The underlying cause is never discarded. DAT_MANAGER_NO_ISSUABLE_CERTIFICATE and DAT_CMS_IMPORT_FAILED carry the reason through each language's exception chaining (cause / __cause__ / InnerException / Unwrap()).