OpenFiat Error Code Registry (OECR)

Abstract#

The OpenFiat Error Code Registry (OECR) defines the canonical set of protocol error codes used throughout the OpenFiat ecosystem.

Every OpenFiat implementation SHALL return standardized error codes for identical failure conditions, regardless of implementation language, operating system, or API transport.

This specification guarantees consistent behavior across:

• OpenFiat Nodes
• SDKs
• Wallets
• Merchant Applications
• JSON-RPC
• REST APIs
• WebSocket APIs
• CLI Tools
• Governance Services
• Oracle Providers
• Risk Providers
• Notification Providers

1. Introduction#

OpenFiat consists of many independent implementations.

Without standardized error codes:

• Applications cannot reliably recover from failures.
• SDK behavior becomes inconsistent.
• Monitoring becomes fragmented.
• Client applications require implementation-specific logic.

This specification defines one canonical error registry for the entire protocol.

2. Design Goals#

The error system SHALL be:

• Deterministic
• Language independent
• Transport independent
• Human readable
• Machine readable
• Extensible
• Backward compatible

3. Error Object#

Every protocol API SHALL expose the following logical structure.

{
  "error": {
    "code": 4004,
    "name": "INSUFFICIENT_AVAILABLE_LIQUIDITY",
    "message": "Advertisement cannot satisfy requested amount.",
    "retryable": false,
    "details": {}
  }
}

4. Error Fields#

Implementations MAY add additional fields but SHALL NOT alter the meaning of the standard fields.

5. Error Code Ranges#

Future specifications SHALL allocate codes only within their assigned range.

6. General Errors (0000)#

7. Network Errors (1000)#

8. Identity Errors (2000)#

9. Advertisement Errors (3000)#

10. Reservation Errors (4000)#

11. Settlement Errors (5000)#

12. Dispute Errors (6000)#

13. Governance Errors (7000)#

14. Notification Errors (8000)#

15. Internal Errors (9000)#

These errors SHALL NOT expose sensitive implementation details.

16. Retry Semantics#

Errors fall into two categories:

Retryable#

Examples:

• NETWORK_UNAVAILABLE
• OPERATION_TIMEOUT
• DELIVERY_FAILED
• BLOCKCHAIN_CONFIRMATION_TIMEOUT

Clients MAY retry automatically using an appropriate backoff strategy.

Non-Retryable#

Examples:

• INVALID_REQUEST
• INVALID_SIGNATURE
• ADVERTISEMENT_EXPIRED
• FLAGGED_DEPOSIT_ADDRESS

Clients SHOULD NOT retry without changing the request.

17. Transport Mapping#

Implementations SHALL preserve the protocol error code regardless of transport.

Examples:

• JSON-RPC: returned in the error object.
• REST: returned in the response body with an appropriate HTTP status.
• WebSocket: returned in the protocol message payload.
• CLI: displayed to the user while preserving the numeric code for scripting.

18. Extensibility#

Future protocol specifications MAY reserve additional codes within their allocated ranges.

Existing codes SHALL NOT be renumbered or reused.

Deprecated codes SHOULD remain reserved permanently to preserve compatibility.

19. Conformance#

A compliant implementation MUST:

• Return standardized protocol error codes.
• Preserve numeric values across transports.
• Preserve symbolic names.
• Avoid exposing sensitive internal implementation details.
• Maintain backward compatibility with previously assigned codes.

20. Summary#

The OpenFiat Error Code Registry provides a single, protocol-wide error vocabulary for every implementation.

By standardizing numeric error codes, symbolic identifiers, retry semantics, and transport mappings, it ensures that all OpenFiat clients and services behave consistently regardless of language or implementation.

The OpenFiat Error Code Registry answers one fundamental question:

"How can every OpenFiat implementation report failures in a deterministic, interoperable, and machine-readable manner?"

The next logical protocol after this would be OFS-8100 — OpenFiat Event Type Registry, which standardizes every protocol event (e.g., AdvertisementCreated, ReservationOpened, SettlementCompleted, DisputeOpened) exchanged across the network. That complements the error registry and gives every implementation a shared event vocabulary.