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.
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 value0. 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.ErrorInfocontaining error code id.- A mandatory
com.google.rpc.RequestInfocontaining (not-truncated) correlation id (or0if correlation id is not available).- An optional
com.google.rpc.RetryInfocontaining retry interval in seconds.- An optional
com.google.rpc.ResourceInfocontaining 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 |