Error Codes

Overview

The majority of the errors are a result of some request processing. They are logged and returned to the user as a failed gRPC response containing the status code, an optional status message and optional metadata.

This approach remains unchanged in principle while we aim at enhancing it by providing:

  • improved consistency of the returned errors across API endpoints,
  • richer error payload format with clearly distinguished machine readable parts to facilitate automated error handling strategies,
  • complete inventory of all error codes with an explanation, suggested resolution and other useful information.

The goal is to enable users, developers and operators to act on the encountered errors in a self-service manner, either in an automated-way or manually.

Configuration

The new error code formats and adapted gRPC response statuses are returned by default starting with the Daml 1.18 SDK release. Clients can still migrate to Daml SDK 1.18 and use the pre-1.18 gRPC status code response behavior by using --use-pre-1.18-error-codes as a command line option. However, this option is deprecated and will be removed in a future release.

Glossary

Error

Represents an occurrence of a failure. Consists of:

  • an error code id,
  • a gRPC status code (determined by its error category),
  • an error category,
  • a correlation id,
  • a human readable message,
  • and optional additional metadata.

You can think of it as an instantiation of an error code.

Error code
Represents a class of failures. Identified by its error code id (we may use error code and error code id interchangeably in this document). Belongs to a single error category.
Error category
A broad categorization of error codes that you can base your error handling strategies on. Map to exactly one gRPC status code. We recommended to deal with errors based on their error category. However, if error category itself is too generic you can act on particular error codes.
Correlation id
A value whose purpose is to allow the user to clearly identify the request, such that the operator can lookup any log information associated with this error. We use request’s submission id for correlation id.

Error Categories

The error categories allow to group errors such that application logic can be built in a sensible way to automatically deal with errors and decide whether to retry a request or escalate to the operator.

TransientServerFailure

Category id: 1

gRPC status code: UNAVAILABLE

Default log level: INFO

Description: One of the services required to process the request was not available.

Resolution: Expectation: transient failure that should be handled by retrying the request with appropriate backoff.

Retry strategy: Retry quickly in load balancer.

ContentionOnSharedResources

Category id: 2

gRPC status code: ABORTED

Default log level: INFO

Description: The request could not be processed due to shared processing resources (e.g. locks or rate limits that replenish quickly) being occupied. If the resource is known (i.e. locked contract), it will be included as a resource info. (Not known resource contentions are e.g. overloaded networks where we just observe timeouts, but can’t pin-point the cause).

Resolution: Expectation: this is processing-flow level contention that should be handled by retrying the request with appropriate backoff.

Retry strategy: Retry quickly (indefinitely or limited), but do not retry in load balancer.

DeadlineExceededRequestStateUnknown

Category id: 3

gRPC status code: DEADLINE_EXCEEDED

Default log level: INFO

Description: The request might not have been processed, as its deadline expired before its completion was signalled. Note that for requests that change the state of the system, this error may be returned even if the request has completed successfully. Note that known and well-defined timeouts are signalled as [[ContentionOnSharedResources]], while this category indicates that the state of the request is unknown.

Resolution: Expectation: the deadline might have been exceeded due to transient resource congestion or due to a timeout in the request processing pipeline being too low. The transient errors might be solved by the application retrying. The non-transient errors will require operator intervention to change the timeouts.

Retry strategy: Retry for a limited number of times with deduplication.

SystemInternalAssumptionViolated

Category id: 4

gRPC status code: INTERNAL

Default log level: ERROR

Description: Request processing failed due to a violation of system internal invariants.

Resolution: Expectation: this is due to a bug in the implementation or data corruption in the systems databases. Resolution will require operator intervention, and potentially vendor support.

Retry strategy: Retry after operator intervention.

MaliciousOrFaultyBehaviour

Category id: 5

gRPC status code: UNKNOWN

Default log level: WARN

Description: Request processing failed due to unrecoverable data loss or corruption (e.g. detected via checksums)

Resolution: Expectation: this can be a severe issue that requires operator attention or intervention, and potentially vendor support.

Retry strategy: Retry after operator intervention.

AuthInterceptorInvalidAuthenticationCredentials

Category id: 6

gRPC status code: UNAUTHENTICATED

Default log level: WARN

Description: The request does not have valid authentication credentials for the operation.

Resolution: Expectation: this is an application bug, application misconfiguration or ledger-level misconfiguration. Resolution requires application and/or ledger operator intervention.

Retry strategy: Retry after app operator intervention.

InsufficientPermission

Category id: 7

gRPC status code: PERMISSION_DENIED

Default log level: WARN

Description: The caller does not have permission to execute the specified operation.

Resolution: Expectation: this is an application bug or application misconfiguration. Resolution requires application operator intervention.

Retry strategy: Retry after app operator intervention.

InvalidIndependentOfSystemState

Category id: 8

gRPC status code: INVALID_ARGUMENT

Default log level: INFO

Description: The request is invalid independent of the state of the system.

Resolution: Expectation: this is an application bug or ledger-level misconfiguration (e.g. request size limits). Resolution requires application and/or ledger operator intervention.

Retry strategy: Retry after app operator intervention.

InvalidGivenCurrentSystemStateOther

Category id: 9

gRPC status code: FAILED_PRECONDITION

Default log level: INFO

Description: The mutable state of the system does not satisfy the preconditions required to execute the request. We consider the whole Daml ledger including ledger config, parties, packages, and command deduplication to be mutable system state. Thus all Daml interpretation errors are reported as as this error or one of its specializations.

Resolution: ALREADY_EXISTS and NOT_FOUND are special cases for the existence and non-existence of well-defined entities within the system state; e.g., a .dalf package, contracts ids, contract keys, or a transaction at an offset. OUT_OF_RANGE is a special case for reading past a range. Violations of the Daml ledger model always result in these kinds of errors. Expectation: this is due to application-level bugs, misconfiguration or contention on application-visible resources; and might be resolved by retrying later, or after changing the state of the system. Handling these errors requires an application-specific strategy and/or operator intervention.

Retry strategy: Retry after app operator intervention.

InvalidGivenCurrentSystemStateResourceExists

Category id: 10

gRPC status code: ALREADY_EXISTS

Default log level: INFO

Description: Special type of InvalidGivenCurrentSystemState referring to a well-defined resource.

Resolution: Same as [[InvalidGivenCurrentSystemStateOther]].

Retry strategy: Inspect resource failure and retry after resource failure has been resolved (depends on type of resource and application).

InvalidGivenCurrentSystemStateResourceMissing

Category id: 11

gRPC status code: NOT_FOUND

Default log level: INFO

Description: Special type of InvalidGivenCurrentSystemState referring to a well-defined resource.

Resolution: Same as [[InvalidGivenCurrentSystemStateOther]].

Retry strategy: Inspect resource failure and retry after resource failure has been resolved (depends on type of resource and application).

InvalidGivenCurrentSystemStateSeekAfterEnd

Category id: 12

gRPC status code: OUT_OF_RANGE

Default log level: INFO

Description: This error is only used by the ledger Api server in connection with invalid offsets.

Resolution: tbd

Retry strategy: Retry after app operator intervention.

BackgroundProcessDegradationWarning

Category id: 13

gRPC status code: N/A

Default log level: WARN

Description: This error category is used internally to signal to the system operator an internal degradation.

Resolution:

Retry strategy: Not an API error, therefore not retryable.

Anatomy of an Error

Errors returned to users contain a gRPC status code, a description and additional machine readable information represented in the rich gRPC error model.

Error Description

We use the standard gRPC description that additionally adheres to our custom message format:

<ERROR_CODE_ID>(<CATEGORY_ID>,<CORRELATION_ID_PREFIX>):<HUMAN_READABLE_MESSAGE>

The constituent parts are:

  • <ERROR_CODE_ID> - a unique non empty string containing at most 63 characters: upper-cased letters, underscores or digits. Identifies corresponding error code id.
  • <CATEGORY_ID> - a small integer identifying the corresponding error category.
  • <CORRELATION_ID_PREFIX> - a string aimed at identifying originating request. Absence of one is indicated by value 0. If present it is an 8 character long prefix of the corresponding request’s submission id. Full correlation id can be found in error’s additional machine readable information (see Additional Machine Readable Information).
  • : - a colon character that serves as a separator for the machine and human readable parts.
  • <HUMAN_READABLE_MESSAGE> - a message targeted at a human reader. Should never be parsed by applications, as the description might change in future releases to improve clarity.

In a concrete example an error description might look like this:

TRANSACTION_NOT_FOUND(11,12345): Transaction not found, or not visible.

Additional Machine Readable Information

We use following error details:

  • A mandatory com.google.rpc.ErrorInfo containing error code id.
  • A mandatory com.google.rpc.RequestInfo containing (not-truncated) correlation id (or 0 if correlation id is not available).
  • An optional com.google.rpc.RetryInfo containing retry interval in seconds.
  • An optional com.google.rpc.ResourceInfo containing information about the resource the failure is based on. Any request that fails due to some well-defined resource issues (such as contract, contract-key, package, party, template, domain, etc..) will contain these. Particular resources are implementation specific and vary across ledger implementations.

Many errors will include more information, but there is no guarantee given that additional information will be preserved across versions.

Error Codes Inventory

1. KVErrors

Errors that are specific to ledgers based on the KV architecture: Daml Sandbox and VMBC.

1.1. KVErrors / Internal

Errors that arise from an internal system misbehavior.

INTERNALLY_DUPLICATE_KEYS

Explanation: The participant didn’t detect an attempt by the transaction submission to use the same key for two active contracts.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

INTERNALLY_INCONSISTENT_KEYS

Explanation: The participant didn’t detect an attempt by the transaction submission to use a stale contract key.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

INVALID_PARTICIPANT_STATE

Explanation: An invalid participant state has been detected.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

MISSING_INPUT_STATE

Explanation: The participant didn’t provide a necessary transaction submission input.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

REJECTION_REASON_NOT_SET

Explanation: A rejection reason has not been set.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

SUBMISSION_FAILED

Explanation: An unexpected error occurred while submitting a command to the ledger.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

VALIDATION_FAILURE

Explanation: An invalid transaction submission was not detected by the participant.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

1.2. KVErrors / Resources

Errors that relate to system resources.

RESOURCE_EXHAUSTED

Explanation: A system resource has been exhausted.

Category: ContentionOnSharedResources

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message

Resolution: Retry the transaction submission or provide the details to the participant operator.

1.3. KVErrors / Time

Errors that relate to the Daml concepts of time.

CAUSAL_MONOTONICITY_VIOLATED

Explanation: At least one input contract’s ledger time is later than that of the submitted transaction.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Retry the transaction submission.

INVALID_RECORD_TIME

Explanation: The record time is not within bounds for reasons other than deduplication, such as excessive latency. Excessive clock skew between the participant and the committer or a time model that is too restrictive may also produce this rejection.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Retry the submission or contact the participant operator.

RECORD_TIME_OUT_OF_RANGE

Explanation: The record time is not within bounds for reasons other than deduplication, such as excessive latency. Excessive clock skew between the participant and the committer or a time model that is too restrictive may also produce this rejection.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Retry the transaction submission or contact the participant operator.

2. ParticipantErrorGroup

2.1. ParticipantErrorGroup / IndexErrors

Errors raised by the Participant Index persistence layer.

2.1.1. ParticipantErrorGroup / IndexErrors / DatabaseErrors

INDEX_DB_INVALID_RESULT_SET

Explanation: This error occurs if the result set returned by a query against the Index database is invalid.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

INDEX_DB_SQL_NON_TRANSIENT_ERROR

Explanation: This error occurs if a non-transient error arises when executing a query against the index database.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact the participant operator.

INDEX_DB_SQL_TRANSIENT_ERROR

Explanation: This error occurs if a transient error arises when executing a query against the index database.

Category: TransientServerFailure

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status UNAVAILABLE including a detailed error message

Resolution: Re-submit the request.

2.2. ParticipantErrorGroup / LedgerApiErrors

Errors raised by or forwarded by the Ledger API.

CONFIGURATION_ENTRY_REJECTED

Explanation: This rejection is given when a new configuration is rejected.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Fetch newest configuration and/or retry.

LEDGER_API_INTERNAL_ERROR

Explanation: This error occurs if there was an unexpected error in the Ledger API.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

PACKAGE_UPLOAD_REJECTED

Explanation: This rejection is given when a package upload is rejected.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Refer to the detailed message of the received error.

PARTICIPANT_BACKPRESSURE

Explanation: This error occurs when a participant rejects a command due to excessive load. Load can be caused by the following factors: 1. when commands are submitted to the participant through its Ledger API, 2. when the participant receives requests from other participants through a connected domain.

Category: ContentionOnSharedResources

Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message

Resolution: Wait a bit and retry, preferably with some backoff factor. If possible, ask other participants to send fewer requests; the domain operator can enforce this by imposing a rate limit.

REQUEST_TIME_OUT

Explanation: This rejection is given when a request processing status is not known and a time-out is reached.

Category: DeadlineExceededRequestStateUnknown

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status DEADLINE_EXCEEDED including a detailed error message

Resolution: Retry for transient problems. If non-transient contact the operator as the time-out limit might be too short.

SERVICE_NOT_RUNNING

Explanation: This rejection is given when the requested service has already been closed.

Category: TransientServerFailure

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status UNAVAILABLE including a detailed error message

Resolution: Retry re-submitting the request. If the error persists, contact the participant operator.

2.2.1. ParticipantErrorGroup / LedgerApiErrors / AuthorizationChecks

Authentication errors.

INTERNAL_AUTHORIZATION_ERROR

Explanation: An internal system authorization error occurred.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact the participant operator.

PERMISSION_DENIED

Explanation: This rejection is given if the supplied authorization token is not sufficient for the intended command. The exact reason is logged on the participant, but not given to the user for security reasons.

Category: InsufficientPermission

Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status PERMISSION_DENIED without any details due to security reasons

Resolution: Inspect your command and your token or ask your participant operator for an explanation why this command failed.

UNAUTHENTICATED

Explanation: This rejection is given if the submitted command does not contain a JWT token on a participant enforcing JWT authentication.

Category: AuthInterceptorInvalidAuthenticationCredentials

Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNAUTHENTICATED without any details due to security reasons

Resolution: Ask your participant operator to provide you with an appropriate JWT token.

2.2.2. ParticipantErrorGroup / LedgerApiErrors / CommandExecution

Errors raised during the command execution phase of the command submission evaluation.

FAILED_TO_DETERMINE_LEDGER_TIME

Explanation: This error occurs if the participant fails to determine the max ledger time of the used contracts. Most likely, this means that one of the contracts is not active anymore which can happen under contention. It can also happen with contract keys.

Category: ContentionOnSharedResources

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message

Resolution: Retry the transaction submission.

2.2.2.1. ParticipantErrorGroup / LedgerApiErrors / CommandExecution / Interpreter

Errors raised during the command interpretation phase of the command submission evaluation.

CONTRACT_NOT_ACTIVE

Explanation: This error occurs if an exercise or fetch happens on a transaction-locally consumed contract.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: This error indicates an application error.

DAML_AUTHORIZATION_ERROR

Explanation: This error occurs if a Daml transaction fails due to an authorization error. An authorization means that the Daml transaction computed a different set of required submitters than you have provided during the submission as actAs parties.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: This error type occurs if there is an application error.

DAML_INTERPRETATION_ERROR

Explanation: This error occurs if a Daml transaction fails during interpretation.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: This error type occurs if there is an application error.

DAML_INTERPRETER_INVALID_ARGUMENT

Explanation: This error occurs if a Daml transaction fails during interpretation due to an invalid argument.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: This error type occurs if there is an application error.

2.2.2.1.1. ParticipantErrorGroup / LedgerApiErrors / CommandExecution / Interpreter / LookupErrors

Errors raised in lookups during the command interpretation phase.

CONTRACT_KEY_NOT_FOUND

Explanation: This error occurs if the Daml engine interpreter cannot resolve a contract key to an active contract. This can be caused by either the contract key not being known to the participant, or not being known to the submitting parties or the contract representing an already archived key.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: This error type occurs if there is contention on a contract.

2.2.2.2. ParticipantErrorGroup / LedgerApiErrors / CommandExecution / Package

Command execution errors raised due to invalid packages.

ALLOWED_LANGUAGE_VERSIONS

Explanation: This error indicates that the uploaded DAR is based on an unsupported language version.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Use a DAR compiled with a language version that this participant supports.

PACKAGE_VALIDATION_FAILED

Explanation: This error occurs if a package referred to by a command fails validation. This should not happen as packages are validated when being uploaded.

Category: MaliciousOrFaultyBehaviour

Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons

Resolution: Contact support.

2.2.2.3. ParticipantErrorGroup / LedgerApiErrors / CommandExecution / Preprocessing

Errors raised during command conversion to the internal data representation.

COMMAND_PREPROCESSING_FAILED

Explanation: This error occurs if a command fails during interpreter pre-processing.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect error details and correct your application.

2.2.3. ParticipantErrorGroup / LedgerApiErrors / ConsistencyErrors

Potential consistency errors raised due to race conditions during command submission or returned as submission rejections by the backing ledger.

CONTRACT_NOT_FOUND

Explanation: This error occurs if the Daml engine can not find a referenced contract. This can be caused by either the contract not being known to the participant, or not being known to the submitting parties or already being archived.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: This error type occurs if there is contention on a contract.

DUPLICATE_COMMAND

Explanation: A command with the given command id has already been successfully processed.

Category: InvalidGivenCurrentSystemStateResourceExists

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message

Resolution: The correct resolution depends on the use case. If the error received pertains to a submission retried due to a timeout, do nothing, as the previous command has already been accepted. If the intent is to submit a new command, re-submit using a distinct command id.

DUPLICATE_CONTRACT_KEY

Explanation: This error signals that within the transaction we got to a point where two contracts with the same key were active.

Category: InvalidGivenCurrentSystemStateResourceExists

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message

Resolution: This error indicates an application error.

INCONSISTENT

Explanation: At least one input has been altered by a concurrent transaction submission.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: The correct resolution depends on the business flow, for example it may be possible to proceed without an archived contract as an input, or the transaction submission may be retried to load the up-to-date value of a contract key.

INCONSISTENT_CONTRACTS

Explanation: An input contract has been archived by a concurrent transaction submission.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: The correct resolution depends on the business flow, for example it may be possible to proceed without the archived contract as an input, or a different contract could be used.

INCONSISTENT_CONTRACT_KEY

Explanation: An input contract key was re-assigned to a different contract by a concurrent transaction submission.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Retry the transaction submission.

INVALID_LEDGER_TIME

Explanation: The ledger time of the submission violated some constraint on the ledger time.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Retry the transaction submission.

2.2.4. ParticipantErrorGroup / LedgerApiErrors / PackageServiceError

Errors raised by the Package Management Service on package uploads.

DAR_NOT_SELF_CONSISTENT

Explanation: This error indicates that the uploaded Dar is broken because it is missing internal dependencies.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Contact the supplier of the Dar.

DAR_VALIDATION_ERROR

Explanation: This error indicates that the validation of the uploaded dar failed.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the error message and contact support.

PACKAGE_SERVICE_INTERNAL_ERROR

Explanation: This error indicates an internal issue within the package service.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Inspect the error message and contact support.

2.2.4.1. ParticipantErrorGroup / LedgerApiErrors / PackageServiceError / Reading

Package parsing errors raised during package upload.

DAR_PARSE_ERROR

Explanation: This error indicates that the content of the Dar file could not be parsed successfully.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the error message and contact support.

INVALID_DAR

Explanation: This error indicates that the supplied dar file was invalid.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the error message for details and contact support.

INVALID_DAR_FILE_NAME

Explanation: This error indicates that the supplied dar file name did not meet the requirements to be stored in the persistence store.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect error message for details and change the file name accordingly

INVALID_LEGACY_DAR

Explanation: This error indicates that the supplied zipped dar is an unsupported legacy Dar.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Please use a more recent dar version.

INVALID_ZIP_ENTRY

Explanation: This error indicates that the supplied zipped dar file was invalid.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the error message for details and contact support.

ZIP_BOMB

Explanation: This error indicates that the supplied zipped dar is regarded as zip-bomb.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the dar and contact support.

2.2.5. ParticipantErrorGroup / LedgerApiErrors / RequestValidation

Validation errors raised when evaluating requests in the Ledger API.

INVALID_ARGUMENT

Explanation: This error is emitted when a submitted ledger API command contains an invalid argument.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the reason given and correct your application.

INVALID_DEDUPLICATION_PERIOD

Explanation: This error is emitted when a submitted ledger API command specifies an invalid deduplication period.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Inspect the error message, adjust the value of the deduplication period or ask the participant operator to increase the maximum deduplication period.

INVALID_FIELD

Explanation: This error is emitted when a submitted ledger API command contains a field value that cannot be understood.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the reason given and correct your application.

LEDGER_ID_MISMATCH

Explanation: Every ledger API command contains a ledger-id which is verified against the running ledger. This error indicates that the provided ledger-id does not match the expected one.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: Ensure that your application is correctly configured to use the correct ledger.

MISSING_FIELD

Explanation: This error is emitted when a mandatory field is not set in a submitted ledger API command.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Inspect the reason given and correct your application.

NON_HEXADECIMAL_OFFSET

Explanation: The supplied offset could not be converted to a binary offset.

Category: InvalidIndependentOfSystemState

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

Resolution: Ensure the offset is specified as a hexadecimal string.

OFFSET_AFTER_LEDGER_END

Explanation: This rejection is given when a read request uses an offset beyond the current ledger end.

Category: InvalidGivenCurrentSystemStateSeekAfterEnd

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status OUT_OF_RANGE including a detailed error message

Resolution: Use an offset that is before the ledger end.

OFFSET_OUT_OF_RANGE

Explanation: This rejection is given when a read request uses an offset invalid in the requests’ context.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Inspect the error message and use a valid offset.

PARTICIPANT_PRUNED_DATA_ACCESSED

Explanation: This rejection is given when a read request tries to access pruned data.

Category: InvalidGivenCurrentSystemStateOther

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

Resolution: Use an offset that is after the pruning offset.

2.2.5.1. ParticipantErrorGroup / LedgerApiErrors / RequestValidation / NotFound

LEDGER_CONFIGURATION_NOT_FOUND

Explanation: The ledger configuration could not be retrieved. This could happen due to incomplete initialization of the participant or due to an internal system error.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: Contact the participant operator.

PACKAGE_NOT_FOUND

Explanation: This rejection is given when a read request tries to access a package which does not exist on the ledger.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: Use a package id pertaining to a package existing on the ledger.

TRANSACTION_NOT_FOUND

Explanation: The transaction does not exist or the requesting set of parties are not authorized to fetch it.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: Check the transaction id and verify that the requested transaction is visible to the requesting parties.

2.2.6. ParticipantErrorGroup / LedgerApiErrors / WriteServiceRejections

Generic submission rejection errors returned by the backing ledger’s write service.

DISPUTED

Deprecation: Corresponds to transaction submission rejections that are not produced anymore.

Explanation: An invalid transaction submission was not detected by the participant.

Category: SystemInternalAssumptionViolated

Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

Resolution: Contact support.

OUT_OF_QUOTA

Deprecation: Corresponds to transaction submission rejections that are not produced anymore.

Explanation: The Participant node did not have sufficient resource quota to submit the transaction.

Category: ContentionOnSharedResources

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message

Resolution: Inspect the error message and retry after after correcting the underlying issue.

PARTY_NOT_KNOWN_ON_LEDGER

Explanation: One or more informee parties have not been allocated.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: Check that all the informee party identifiers are correct, allocate all the informee parties, request their allocation or wait for them to be allocated before retrying the transaction submission.

SUBMITTER_CANNOT_ACT_VIA_PARTICIPANT

Explanation: A submitting party is not authorized to act through the participant.

Category: InsufficientPermission

Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status PERMISSION_DENIED without any details due to security reasons

Resolution: Contact the participant operator or re-submit with an authorized party.

SUBMITTING_PARTY_NOT_KNOWN_ON_LEDGER

Explanation: The submitting party has not been allocated.

Category: InvalidGivenCurrentSystemStateResourceMissing

Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

Resolution: Check that the party identifier is correct, allocate the submitting party, request its allocation or wait for it to be allocated before retrying the transaction submission.

Error Codes Migration Guide

The Ledger API gRPC error codes change introduced in the Daml SDK 1.18 release involves breaking compatibility with previous releases for some service Ledger API endpoints.

The table below outlines all the cases and error conditions when a Ledger API service endpoint returns a different gRPC status code in comparison to the pre-1.18 releases.

Common Ledger API changes

The table below outlines generic gRPC status code changes pertaining to the Ledger API and apply to all ledger backends. For changes specific to a ledger backend, check the next subsections.

(Note that status codes that have not changed for particular endpoints are not listed in the tables below.)

ActiveContractsService.getActiveContracts

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
NOT_FOUND FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when attempting to access the data that has already been pruned. PARTICIPANT_PRUNED_DATA_ACCESSED
NOT_FOUND NOT_FOUND The ledger id from the request does match the participant’s ledger id. LEDGER_ID_MISMATCH

CommandCompletionService.completionStream

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
NOT_FOUND FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when attempting to access the data that has already been pruned. PARTICIPANT_PRUNED_DATA_ACCESSED
NOT_FOUND NOT_FOUND The ledger id from the request does match the participant’s ledger id. LEDGER_ID_MISMATCH

CommandService.submitAndWait

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED DEADLINE_EXCEEDED DEADLINE_EXCEEDED is now returned on Command Service submissions timeouts. REQUEST_TIME_OUT
ABORTED INTERNAL INTERNAL is not returned on Command Service submissions on unexpected errors. LEDGER_API_INTERNAL_ERROR
ABORTED UNAVAILABLE UNAVAILABLE is now returned on Command Service submissions on backpressure. SERVICE_NOT_RUNNING
RESOURCE_EXHAUSTED ABORTED ABORTED is now returned on Command Service submissions on backpressure. PARTICIPANT_BACKPRESSURE
UNAVAILABLE NOT_FOUND NOT_FOUND can now be returned when a ledger configuration was not found. LEDGER_CONFIGURATION_NOT_FOUND
UNAVAILABLE UNAVAILABLE A service is not running. SERVICE_NOT_RUNNING

CommandService.submitAndWaitForTransaction

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED DEADLINE_EXCEEDED DEADLINE_EXCEEDED is now returned on Command Service submissions timeouts. REQUEST_TIME_OUT
ABORTED INTERNAL INTERNAL is not returned on Command Service submissions on unexpected errors. LEDGER_API_INTERNAL_ERROR
ABORTED UNAVAILABLE UNAVAILABLE is now returned on Command Service submissions on backpressure. SERVICE_NOT_RUNNING
RESOURCE_EXHAUSTED ABORTED ABORTED is now returned on Command Service submissions on backpressure. PARTICIPANT_BACKPRESSURE
UNAVAILABLE NOT_FOUND NOT_FOUND can now be returned when a ledger configuration was not found. LEDGER_CONFIGURATION_NOT_FOUND
UNAVAILABLE UNAVAILABLE A service is not running. SERVICE_NOT_RUNNING

CommandService.submitAndWaitForTransactionId

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED DEADLINE_EXCEEDED DEADLINE_EXCEEDED is now returned on Command Service submissions timeouts. REQUEST_TIME_OUT
ABORTED INTERNAL INTERNAL is not returned on Command Service submissions on unexpected errors. LEDGER_API_INTERNAL_ERROR
ABORTED UNAVAILABLE UNAVAILABLE is now returned on Command Service submissions on backpressure. SERVICE_NOT_RUNNING
RESOURCE_EXHAUSTED ABORTED ABORTED is now returned on Command Service submissions on backpressure. PARTICIPANT_BACKPRESSURE
UNAVAILABLE NOT_FOUND NOT_FOUND can now be returned when a ledger configuration was not found. LEDGER_CONFIGURATION_NOT_FOUND
UNAVAILABLE UNAVAILABLE A service is not running. SERVICE_NOT_RUNNING

CommandService.submitAndWaitForTransactionTree

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED DEADLINE_EXCEEDED DEADLINE_EXCEEDED is now returned on Command Service submissions timeouts. REQUEST_TIME_OUT
ABORTED INTERNAL INTERNAL is not returned on Command Service submissions on unexpected errors. LEDGER_API_INTERNAL_ERROR
ABORTED UNAVAILABLE UNAVAILABLE is now returned on Command Service submissions on backpressure. SERVICE_NOT_RUNNING
RESOURCE_EXHAUSTED ABORTED ABORTED is now returned on Command Service submissions on backpressure. PARTICIPANT_BACKPRESSURE
UNAVAILABLE NOT_FOUND NOT_FOUND can now be returned when a ledger configuration was not found. LEDGER_CONFIGURATION_NOT_FOUND
UNAVAILABLE UNAVAILABLE A service is not running. SERVICE_NOT_RUNNING

CommandSubmissionService.submit

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
UNAVAILABLE NOT_FOUND NOT_FOUND can now be returned when a ledger configuration was not found. LEDGER_CONFIGURATION_NOT_FOUND

ConfigManagementService.setTimeModel

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED DEADLINE_EXCEEDED DEADLINE_EXCEEDED can now be returned when a time out was reached. REQUEST_TIME_OUT
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when a configuration update was rejected. CONFIGURATION_ENTRY_REJECTED
UNAVAILABLE NOT_FOUND NOT_FOUND can now be returned when a ledger configuration was not found. LEDGER_CONFIGURATION_NOT_FOUND

GrpcHealthService.check

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
NOT_FOUND INVALID_ARGUMENT INVALID_ARGUMENT can now be returned when the received request contains invalid values. INVALID_ARGUMENT

GrpcHealthService.watch

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
NOT_FOUND INVALID_ARGUMENT INVALID_ARGUMENT can now be returned when the received request contains invalid values. INVALID_ARGUMENT

PackageManagementService.uploadDarFile

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED DEADLINE_EXCEEDED DEADLINE_EXCEEDED can now be returned when a time out was reached. REQUEST_TIME_OUT
INVALID_ARGUMENT FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when a package upload was rejected. PACKAGE_UPLOAD_REJECTED
INVALID_ARGUMENT INVALID_ARGUMENT Generic error for invalid arguments in the request. INVALID_ARGUMENT

ParticipantPruningService.prune

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
INVALID_ARGUMENT FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when the supplied pruning offset is not before the ledger end. OFFSET_OUT_OF_RANGE
INVALID_ARGUMENT INVALID_ARGUMENT Generic error for invalid arguments in the request. INVALID_ARGUMENT
INVALID_ARGUMENT INVALID_ARGUMENT The offset is not in hexadecimal format. NON_HEXADECIMAL_OFFSET

PartyManagementService.allocateParty

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED DEADLINE_EXCEEDED DEADLINE_EXCEEDED can now be returned when a time out was reached. REQUEST_TIME_OUT

SubmissionService.submit

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
ABORTED ABORTED Failed to determine ledger time. FAILED_TO_DETERMINE_LEDGER_TIME
ABORTED ALREADY_EXISTS ALREADY_EXISTS can now be returned when there was a duplicate contract key during interpretation. DUPLICATE_CONTRACT_KEY_DURING_INTERPRETATION
ABORTED INTERNAL INTERNAL can now be returned when validation fails on a mismatch during relay of the submitted transaction. LEDGER_API_INTERNAL_ERROR
ABORTED NOT_FOUND NOT_FOUND can now be returned when contract key was not found during interpretation. CONTRACT_NOT_FOUND
INVALID_ARGUMENT FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when a Daml transaction fails during interpretation. DAML_INTERPRETATION_ERROR
INVALID_ARGUMENT INTERNAL INTERNAL can now be returned in case of internal errors. LEDGER_API_INTERNAL_ERROR
INVALID_ARGUMENT INVALID_ARGUMENT Invalid argument detected before command execution. ALLOWED_LANGUAGE_VERSIONS, COMMAND_PREPROCESSING_FAILED, DAML_AUTHORIZATION_ERROR
INVALID_ARGUMENT INVALID_ARGUMENT Invalid argument detected by the Daml interpreter. DAML_INTERPRETER_INVALID_ARGUMENT
INVALID_ARGUMENT NOT_FOUND NOT_FOUND can now be returned when a Daml interpreter can not resolve a contract key to an active contract. CONTRACT_KEY_NOT_FOUND
INVALID_ARGUMENT NOT_FOUND NOT_FOUND can now be returned when a Daml transaction was referring to a package which was not known to the participant. MISSING_PACKAGE
INVALID_ARGUMENT NOT_FOUND NOT_FOUND can now be returned when an exercise or fetch happens on a transaction-locally consumed contract. CONTRACT_NOT_ACTIVE
INVALID_ARGUMENT UNKNOWN UNKNOWN can now be returned when package validation fails. PACKAGE_VALIDATION_FAILED
UNAVAILABLE NOT_FOUND NOT_FOUND can now be returned when a ledger configuration was not found. LEDGER_CONFIGURATION_NOT_FOUND

TransactionService.getFlatTransactionByEventId

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
NOT_FOUND INVALID_ARGUMENT INVALID_ARGUMENT can now be returned when the received request contains invalid values. INVALID_ARGUMENT
NOT_FOUND NOT_FOUND The ledger id from the request does match the participant’s ledger id. LEDGER_ID_MISMATCH

TransactionService.getTransactionByEventId

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
NOT_FOUND INVALID_ARGUMENT INVALID_ARGUMENT can now be returned when the received request contains invalid values. INVALID_ARGUMENT
NOT_FOUND NOT_FOUND The ledger id from the request does match the participant’s ledger id. LEDGER_ID_MISMATCH
NOT_FOUND NOT_FOUND Transaction was not found. TRANSACTION_NOT_FOUND

TransactionService.getTransactionTrees

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
INVALID_ARGUMENT FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when the supplied offset was out of range. OFFSET_OUT_OF_RANGE
INVALID_ARGUMENT INVALID_ARGUMENT A field is missing in the request. MISSING_FIELD
INVALID_ARGUMENT INVALID_ARGUMENT Generic error for invalid arguments in the request. INVALID_ARGUMENT
INVALID_ARGUMENT INVALID_ARGUMENT Invalid field detected in the request. INVALID_FIELD
NOT_FOUND FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when attempting to access the data that has already been pruned. PARTICIPANT_PRUNED_DATA_ACCESSED

TransactionService.getTransactions

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code id
INVALID_ARGUMENT FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when the supplied offset was out of range. OFFSET_OUT_OF_RANGE
INVALID_ARGUMENT INVALID_ARGUMENT A field is missing in the request. MISSING_FIELD
INVALID_ARGUMENT INVALID_ARGUMENT Generic error for invalid arguments in the request. INVALID_ARGUMENT
INVALID_ARGUMENT INVALID_ARGUMENT Invalid field detected in the request. INVALID_FIELD
NOT_FOUND FAILED_PRECONDITION FAILED_PRECONDITION can now be returned when attempting to access the data that has already been pruned. PARTICIPANT_PRUNED_DATA_ACCESSED
NOT_FOUND NOT_FOUND The ledger id from the request does match the participant’s ledger id. LEDGER_ID_MISMATCH

Sandbox (classic)

The following gRPC status codes have changed for submission rejections in Sandbox classic.

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code ID
ABORTED ALREADY_EXISTS ALREADY_EXISTS is now returned on duplicate contract key transaction rejections. DUPLICATE_CONTRACT_KEY
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION is now returned on invalid ledger time transaction rejections. INVALID_LEDGER_TIME
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION is now returned on transaction rejections on consistency errors. INCONSISTENT, INCONSISTENT_CONTRACT_KEY
ABORTED NOT_FOUND NOT_FOUND is now returned on transaction rejections on not found contract. CONTRACT_NOT_FOUND
ABORTED NOT_FOUND NOT_FOUND is now returned on rejections occurring due to missing ledger configuration. LEDGER_CONFIGURATION_NOT_FOUND
INVALID_ARGUMENT INTERNAL INTERNAL is now returned on transaction rejections on system faults. DISPUTED
INVALID_ARGUMENT NOT_FOUND PARTY_NOT_KNOWN_ON_LEDGER is now returned on transaction rejections on unallocated parties. PARTY_NOT_KNOWN_ON_LEDGER

NOTE: Additionally, UNAVAILABLE is now returned when trying to reset the Sandbox server during an ongoing re-initialization (was FAILED_PRECONDITION).

Daml Sandbox and VMBC

The following gRPC status codes have changed for submission rejections in the Ledger API backed by KV-based ledgers (Daml Sandbox and VMBC).

gRPC status code (before SDK 1.18) gRPC status code (since SDK 1.18) Remarks Ledger API error code ID
ABORTED ALREADY_EXISTS ALREADY_EXISTS is now returned on duplicate resource transaction rejections. DUPLICATE_CONTRACT_KEY, DUPLICATE_COMMAND
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION is now returned on a submission that has violated some constraint on ledger time. INVALID_LEDGER_TIME
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION is now returned on consistency error transaction rejections. INCONSISTENT, INCONSISTENT_CONTRACT_KEY, INCONSISTENT_CONTRACTS
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION is now returned on invalid record time transaction rejections. INVALID_RECORD_TIME
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION is now returned on transaction rejections on record time bounds violations. RECORD_TIME_OUT_OF_RANGE
ABORTED FAILED_PRECONDITION FAILED_PRECONDITION is now returned on transaction rejections on time monotonicity violations. CAUSAL_MONOTONICITY_VIOLATED
ABORTED INTERNAL INTERNAL is now returned on submissions missing mandatory participant input. MISSING_INPUT_STATE
INVALID_ARGUMENT INTERNAL INTERNAL is now returned on an invalid transaction submission that was not detected by the participant. DISPUTED
INVALID_ARGUMENT INTERNAL INTERNAL is now returned on consistency errors that should have been caught by the participant. INTERNALLY_INCONSISTENT_KEYS, INTERNALLY_DUPLICATE_KEYS
INVALID_ARGUMENT INTERNAL INTERNAL is now returned on invalid transaction submissions. VALIDATION_FAILURE
INVALID_ARGUMENT INTERNAL INTERNAL is now returned on transaction rejections when an invalid participant state has been detected. INVALID_PARTICIPANT_STATE
INVALID_ARGUMENT NOT_FOUND NOT_FOUND is now returned on transaction rejections on unallocated parties. SUBMITTING_PARTY_NOT_KNOWN_ON_LEDGER, PARTY_NOT_KNOWN_ON_LEDGER
UNKNOWN INTERNAL INTERNAL is now returned on transaction rejections without a status. REJECTION_REASON_NOT_SET