Error reference

Date	Responsible	Changes
November 3, 2022	@Luis Fidelis	Initial version
February 10, 2023	@Tomislav Herman	Renamed error status to reason, classified error reasons in different categories which is reflected in the prefix. Added new error reasons for bridge, core and reorganized other by categories. Removed error classes examples since it’s outdated now, and also because this is client facing error reference where implementation details are not relevant. Reorganized errors in sections by category and descriptions.
June 14, 2023	@Omar Monterrey	Added `core.routing-failed` and `core.thread-size-exceeded` errors
December 12, 2023	@Luis Fidelis	Added `record.drop-rejected` and `core.bridge-unsupported-operation` errors
February 20, 2024	@Tomislav Herman	Added `bridge.command-unsupported` error
February 27, 2024	@Omar Monterrey	Added `core.limit-exceeded` error
March 19, 2024	@Luis Fidelis	Added `bridge.incorrect-fee` error
May 10, 2024	@Omar Monterrey	Added `bridge.proxy-response-invalid` error
July 11, 2024	@Luis Fidelis	Added `record.labels-policy-violation` error
October 9, 2024	@Juan Pablo Ottaviano	Added `bridge.core-invalid-access` and `bridge.transfer-information-invalid` errors

Authentication and Security errors

These errors are related to authentication and security access rules. Thrown when security credentials contained in request JWT are invalid or performing some action in ledger is forbidden for presented credentials.

These errors happen in API request processing so they have response HTTP status codes associated.

REASON	DESCRIPTION	HTTP STATUS
auth.unauthorized	Security credentials and missing or the credentials presented are invalid or expired. Credentials are invalid when JWT signature is invalid or the JWT payload is invalid.	401
auth.forbidden	Performing an action in ledger or on record is not allowed with current security credentials based on the access rules.	403

Cryptographic integrity errors

These errors are related to integrity of cryptographic entities: hashes, signatures and keys.

Validation which produces these errors happens in API request processing so they also have response HTTP status codes associated.

REASON	DESCRIPTION	HTTP STATUS
crypto.hash-invalid	Received record hash doesn’t match the record.	422
crypto.parent-hash-invalid	Received parent hash in update request doesn’t match the parent record.	422
crypto.signature-invalid	Any of received record signatures is invalid. Triggered by first invalid signature.	422
crypto.signature-missing	Received record doesn’t have any signature.	422

Generic API level errors

These errors happen in API request processing.

They originate from the first layer of request processing which is not aware of ledger record semantics and they also have response HTTP status codes associated.

REASON	DESCRIPTION	HTTP STATUS
api.body-malformed	Invalid request body format, can’t be parsed as JSON.	400
api.query-malformed	Invalid request query parameter format, used when the request parameters can’t be parsed.	400
api.route-not-found	Requested method and path doesn’t exist	404
api.request-timeout	Request processing took too long.	408
api.rate-limit-exceeded	Number of requests exceeded the rate limit. Try again later.	429
api.unexpected-error	Unexpected error when processing request.	500

Record level errors

Errors related to ledger records. Used when something is wrong with requested or submitted records.

These errors happen in API request processing so they also have response HTTP status codes associated.

REASON	DESCRIPTION	HTTP STATUS
record.not-found	Requested record by handle doesn’t exist in the ledger database.	404
record.relation-not-found	Related record referenced in the received record `<record>.data.<relation>` doesn’t exist in the ledger database.	422
record.duplicated	Record with same handle already exists in the ledger database.	409
record.schema-invalid	Received record doesn’t match the expected record schema. Also used when request path or query params doesn’t match expected request schema.	422
record.invalid	Record schema is correct but it cannot be processed by the server.	422
record.drop-rejected	Record drop cannot be processed by the server due to an internal validation.	422
labels-policy-violation	Label(s) can not be processed due to policy violation	422

Core ledger errors

These errors are thrown by the ledger core which handles intents and balance movements. Since the ledger core processes intents asynchronously ****in the background, these errors will not be sent in HTTP responses, so there are no HTTP status codes associated with this error group.

These errors are added to intent signature when they happen. Added signature will have custom.status = 'aborted' and custom.reason equal to one of the reasons in this reason group core.* and custom.detail with a message which explains error in more detail.

REASON	DESCRIPTION	HTTP STATUS
core.source-invalid	Source of balance movement can’t be resolved to valid wallet.	N/A
core.target-invalid	Target of balance movement can’t be resolved to valid wallet.	N/A
core.symbol-invalid	Symbol of balance movement can’t be resolved.	N/A
core.insufficient-balance	Source wallet of balance movement doesn’t have enough balance.	N/A
core.intent-expired	Intent expired before all required signatures are collected. Signature with this `reason` is added to intent by a background job which periodically checks intents and aborts all which are still pending after predefined timeout.	N/A
core.limit-exceeded	Intent execution exceeded a limit. Limits can be exceeded either by source or target wallet and for different reasons. The `detail` of the error will contain more details.	N/A
core.bridge-prepare-failed	Bridge reported fail in prepare phase. When ledger core adds a signature with this `reason` it will set `failId` to the `reason` received in failed signature from a bridge.	N/A
core.bridge-unreachable	Unable to deliver prepare event to bridge. Used when all attempts defined by retry strategy failed.	N/A
core.bridge-unsupported-operation	Unable to send request to bridge because it doesn't support the operation.	N/A
core.routing-failed	When the routing of an intent couldn't be performed. For example when the target wallet has routes defined but none of them matches the current intent.	N/A
core.thread-size-exceeded	When the routing of an intent is too depth. Used to avoid routing loops on wallets.	N/A
core.unexpected-error	Unexpected error happened in ledger core when processing intent.	N/A

External bridge errors

These errors are related to processing of entries on external systems or bridges in entry prepare phase. These errors also don’t have HTTP status codes associated since they happen in background when intent is processed by bridges.

Bridge needs to report an error by adding a signature to intent (included in entry) by calling ledger API

POST /v2/intents/:handle/sign

Signature needs to have have with custom.status = 'failed' , custom.reason equal to one of the reasons in this reason group bridge.* custom.detail with a message which explains error in more detail. Optional, but recommended, is the custom.failId which is reserved for reference of error in external system, usually error code or error class. This additional field is useful for having a reference for diagnostic purposes. Bridge can report just the errors from this error group, all other errors will be rejected by the ledger API.

Status	Reason	Detail
N/A	bridge.account-not-found	Account referenced in entry does not exist in the bridge system.
N/A	bridge.account-inactive	Account referenced in entry is inactive in the bridge system, but it exists in the system.
N/A	bridge.account-insufficient-balance	Insufficient balance on the account in the bridge system to perform the financial transaction specified in entry.
N/A	bridge.account-limit-exceeded	Account has enough balance but has already exceeded the transactional limit (for any period).
N/A	bridge.entry-rejected	Entry was rejected for the referenced account. It can be either rejection of debit for the source, or rejection of credit for the target account.
N/A	bridge.entry-hash-invalid	Hash of the received entry is invalid.
N/A	bridge.entry-signature-invalid	Any of received entry signatures is invalid. Triggered by first invalid signature.
N/A	bridge.entry-signature-mismatch	All entry signatures are valid but there is no matching signature with the expected ledger key.
N/A	bridge.entry-signature-missing	Received entry doesn’t have any signature.
N/A	bridge.entry-schema-invalid	Received entry doesn’t match the expected schema. Returned in case when root or data fields don’t match the schema or the included intent doesn’t match the intent schema.
N/A	bridge.entry-mismatch	Data received in entry doesn’t match the intent included in the entry. In case when source, target, amount or symbol in the entry doesn’t match the related claim in the intent.
N/A	bridge.entry-duplicated	Different entry for same intent claim with same source or target was already received before. Used to reject double spending for the same intent. This error should not be reported when handling idempotency, meaning when the action with same handle is received multiple times.
N/A	bridge.entry-timeout	Too much time passed from initiation of intent to receiving the entry which includes this intent.
N/A	bridge.intent-hash-invalid	Hash of the intent in the received entry is invalid.
N/A	bridge.intent-signature-invalid	Any of signatures of the intent received in entry is invalid. Triggered by first invalid signature.
N/A	bridge.intent-signature-missing	Intent received in entry doesn’t have any signature.
N/A	bridge.intent-unrelated	Intent received in entry can’t be recognized or correlated in the bridge. It can means that it’s not signed by expected key or the intent reference doesn’t exist in the bridge system.
N/A	bridge.command-unsupported	Bridge doesn’t support received command. For example if bridge can’t process abort of credit it will add proof to intent with status `error` and this reason and by doing that it will suspend intent abort process.
N/A	bridge.fraud-detected	Entry was marked as fraud based on analysis of intent in the bridge.
N/A	bridge.ledger-failed	Error happened when calling ledger API. If bridge needs to perform some api calls to ledger as a precondition to signing intent. Recommended to set the `failId` to the error `reason` received from ledger in the signature which reports the error.
N/A	bridge.core-unreachable	Can’t access the (banking) core system from the bridge. Usually if the core system is down for maintenance or has a regular scheduled downtime which sometimes is a normal behaviour of financial institutions.
N/A	bridge.unexpected-core-error	Generic error from the (banking) core system. If the error is received from the core system which can’t be classified as any of existing bridge errors. Recommended in related signature to set the `failId` to type identifier of internal core error (error code or class name or similar).
N/A	bridge.unexpected-error	Unexpected error happened on bridge when processing entry. In case when error happens in the bridge process which handles the action and can’t be classified as any of existing bridge errors. Recommended to set the `failId` to error type identifier (error class name or similar) and `detail` to error message in the signature which reports the error.
N/A	bridge.incorrect-fee	Bridge could not validate the fee of transaction or it is invalid.
N/A	bridge.proxy-response-invalid	Response returned from the bridge for a proxied request is not valid. This can happen due to `schema` validation.
N/A	bridge.core-access-invalid	Cant validate access to the (banking) core system
N/A	bridge.transfer-information-invalid	(Banking) core system cant validate transfer information received