Error Codes¶

DecentDB now uses stable broad categories plus structured diagnostics for machine-readable behavior.

For vNext, bindings should treat the broad status as the compatibility floor and subcode plus retryable/permanent as the primary handling key.

• DDB_ABI_VERSION is 7.
• ddb_last_error_json(char **out_json) is the stable C ABI accessor for structured diagnostics.
• The first public slice uses a stable subcode family with optional SQLSTATE and bounded redacted context.

Broad Status Families¶

Broad categories stay stable for compatibility and broad branching.

Structured Diagnostic JSON¶

The structured diagnostic is versioned and returned by ddb_last_error_json:

{
  "version": 1,
  "code": 5,
  "code_name": "ERR_SQL",
  "subcode": "sql.relation_not_found",
  "sqlstate": "42P01",
  "message": "relation not found",
  "retryable": false,
  "permanent": true,
  "redaction": "default",
  "relation": "users",
  "docs": "errors/sql-relation-not-found"
}

Required fields are:

• version: diagnostic schema version, starts at 1.
• code: numeric category.
• code_name: broad category name, without ABI prefix.
• subcode: stable machine-readable condition.
• message: human-readable text (non-contractual).
• retryable: may a retry succeed without changing input.
• permanent: will the same inputs keep failing until external state or policy changes.
• redaction: active policy (default initially).
• docs: stable diagnostics anchor.

Optional fields are omitted if unknown:

• sqlstate: SQLSTATE-compatible code where unambiguous.
• relation, column, index, constraint, policy, branch, sync_scope, sync_peer, changeset_id.
• process_owner, wal, format, parameter, path, hint, doctor, details.

First Slice Subcodes (vNext)¶

These are the first diagnostics expected for stable projection.

Keep this list as the implementation expands.

CLI / HTTP / WASM Output¶

CLI and HTTP JSON responses should include both the legacy short code and diagnostic object:

{
  "ok": false,
  "error": {
    "code": "ERR_SQL",
    "native_code": 5,
    "subcode": "sql.relation_not_found",
    "message": "relation not found",
    "diagnostic": {
      "version": 1,
      "code": 5,
      "code_name": "ERR_SQL",
      "subcode": "sql.relation_not_found",
      "sqlstate": "42P01",
      "retryable": false,
      "permanent": true,
      "redaction": "default",
      "relation": "users",
      "docs": "errors/sql-relation-not-found"
    }
  }
}

Do not replace the message from the diagnostic object and do not rely on parsing free-text for behavior.

Redaction by Default¶

The default diagnostics contract excludes:

• SQL parameter values
• Raw SQL text
• Encryption keys or derived key material
• Full paths
• Sync tokens
• Raw audit context values

Allowed default context includes relation/object metadata, redacted path descriptors, process or WAL identifiers, and bounded technical counters.

Binding Projection¶

All maintained bindings should keep existing exception families and add structured diagnostic access:

• code and native_code where relevant.
• subcode and optional sqlstate.
• retryable and permanent.
• Raw diagnostic JSON or equivalent map for forward compatibility.

Bindings should parse diagnostic.subcode and diagnostic.code_name for automation rather than matching message strings.

Troubleshooting Anchors¶

The docs field uses stable anchor IDs. See:

• errors/sql-relation-not-found
• errors/constraint-unique
• errors/queue-write-timeout
• errors/busy-writer-lock
• errors/io-disk-full
• errors/corruption-page-checksum
• errors/sync-retention-blocked
• errors/branch-merge-conflict

Compatibility Checklist¶

• Existing broad status values must not change.
• Required diagnostic fields may not be removed.
• New optional fields are backward-compatible.
• Subcodes must keep stable spelling and meaning during a compatibility cycle.
• Changing retryable or permanent semantics requires release note coverage.
• Message text changes are allowed and should not be used as contracts.

Release Guardrails¶

Run the phase-5 consistency check when preparing a release:

python scripts/validate_error_diagnostics.py

That check validates:

• First-slice subcodes are documented.
• Troubleshooting anchor coverage for all first-slice anchors.
• Required docs touchpoints (error-codes, c-cpp, and doctor).
• Binding smoke fixture coverage status.