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.
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.
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 with milliseconds resolution.- 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.
Prevent Security Leaks in Error Codes¶
For any error that could leak information to an attacker, the system will return an error message via the API that will not leak any valuable information. The log file will contain the full error message.
Work With Error Codes¶
This example shows how a user can extract the relevant error information.
object SampleClientSide {
import com.google.rpc.ResourceInfo
import com.google.rpc.{ErrorInfo, RequestInfo, RetryInfo}
import io.grpc.StatusRuntimeException
import scala.jdk.CollectionConverters._
def example(): Unit = {
try {
DummmyServer.serviceEndpointDummy()
} catch {
case e: StatusRuntimeException =>
// Converting to a status object.
val status = io.grpc.protobuf.StatusProto.fromThrowable(e)
// Extracting gRPC status code.
assert(status.getCode == io.grpc.Status.Code.ABORTED.value())
assert(status.getCode == 10)
// Extracting error message, both
// machine oriented part: "MY_ERROR_CODE_ID(2,full-cor):",
// and human oriented part: "A user oriented message".
assert(status.getMessage == "MY_ERROR_CODE_ID(2,full-cor): A user oriented message")
// Getting all the details
val rawDetails: Seq[com.google.protobuf.Any] = status.getDetailsList.asScala.toSeq
// Extracting error code id, error category id and optionally additional metadata.
assert {
rawDetails.collectFirst {
case any if any.is(classOf[ErrorInfo]) =>
val v = any.unpack(classOf[ErrorInfo])
assert(v.getReason == "MY_ERROR_CODE_ID")
assert(v.getMetadataMap.asScala.toMap == Map("category" -> "2", "foo" -> "bar"))
}.isDefined
}
// Extracting full correlation id, if present.
assert {
rawDetails.collectFirst {
case any if any.is(classOf[RequestInfo]) =>
val v = any.unpack(classOf[RequestInfo])
assert(v.getRequestId == "full-correlation-id-123456790")
}.isDefined
}
// Extracting retry information if the error is retryable.
assert {
rawDetails.collectFirst {
case any if any.is(classOf[RetryInfo]) =>
val v = any.unpack(classOf[RetryInfo])
assert(v.getRetryDelay.getSeconds == 123, v.getRetryDelay.getSeconds)
assert(v.getRetryDelay.getNanos == 456 * 1000 * 1000, v.getRetryDelay.getNanos)
}.isDefined
}
// Extracting resource if the error pertains to some well defined resource.
assert {
rawDetails.collectFirst {
case any if any.is(classOf[ResourceInfo]) =>
val v = any.unpack(classOf[ResourceInfo])
assert(v.getResourceType == "CONTRACT_ID")
assert(v.getResourceName == "someContractId")
}.isDefined
}
}
}
}
Error Categories Inventory¶
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. This error is exposed on the API with grpc-status INTERNAL without any details for security reasons
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.
AuthInterceptorInvalidAuthenticationCredentials¶
Category id: 6
gRPC status code: UNAUTHENTICATED
Default log level: WARN
Description: The request does not have valid authentication credentials for the operation. This error is exposed on the API with grpc-status UNAUTHENTICATED without any details for security reasons
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 application 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. This error is exposed on the API with grpc-status PERMISSION_DENIED without any details for security reasons
Resolution: Expectation: this is an application bug or application misconfiguration. Resolution requires application operator intervention.
Retry strategy: Retry after application operator intervention.
SecurityAlert¶
Category id: 5
gRPC status code: INVALID_ARGUMENT
Default log level: WARN
Description: A potential attack or a faulty peer component has been detected. This error is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.
Resolution: Expectation: this can be a severe issue that requires operator attention or intervention, and potentially vendor support. It means that the system has detected invalid information that can be attributed to either faulty or malicious manipulation of data coming from a peer source.
Retry strategy: Errors in this category are non-retryable.
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 application 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, users and command deduplication to be mutable system state. Thus all Daml interpretation errors are reported 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 application 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: Expectation: this error is only used by the Ledger API server in connection with invalid offsets.
Retry strategy: Retry after application 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: Inspect details of the specific error for more information.
Retry strategy: Not an API error, therefore not retryable.
InternalUnsupportedOperation¶
Category id: 14
gRPC status code: UNIMPLEMENTED
Default log level: ERROR
Description: This error category is used to signal that an unimplemented code-path has been triggered by a client or participant operator request. This error is exposed on the API with grpc-status UNIMPLEMENTED without any details for security reasons
Resolution: This error is caused by a ledger-level misconfiguration or by an implementation bug. Resolution requires participant operator intervention.
Retry strategy: Errors in this category are non-retryable.
Error Codes Inventory¶
1. KvErrors¶
Errors that are specific to ledgers based on the KV architecture: Daml Sandbox and VMBC.
1.1. KvErrors / Consistency¶
Errors that highlight transaction consistency issues in the committer context.
INCONSISTENT_INPUT¶
Explanation: At least one input has been altered by a concurrent transaction submission.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED 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.
VALIDATION_FAILURE¶
Explanation: Validation of a transaction submission failed using on-ledger data.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Either some input contracts have been pruned or the participant is misbehaving.
1.2. KvErrors / Internal¶
Errors that arise from an internal system misbehavior.
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. It is exposed on the API with grpc-status INTERNAL without any details for 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. It is exposed on the API with grpc-status INTERNAL without any details for 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. It is exposed on the API with grpc-status INTERNAL without any details for 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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: Contact support.
1.3. KvErrors / Resources¶
Errors that relate to system resources.
RESOURCE_EXHAUSTED¶
Deprecation: Replaced by RESOURCE_OVERLOADED. Since: 2.3.0
Explanation: A system resource has been exhausted.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and 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.
RESOURCE_OVERLOADED¶
Explanation: A system resource is overloaded.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and 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.4. 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 and 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 and 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_BOUNDS¶
Explanation: The record time is not within bounds for reasons such as excessive latency, excessive clock skew between the participant and the committer or a time model that is too restrictive.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED 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 and 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 / CommonErrors¶
Common errors raised in Daml services and components.
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 and 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.
SERVER_IS_SHUTTING_DOWN¶
Explanation: This rejection is given when the participant server is shutting down.
Category: TransientServerFailure
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.
Resolution: Contact the participant operator.
SERVICE_INTERNAL_ERROR¶
Explanation: This error occurs if one of the services encountered an unexpected exception.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: Contact support.
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 and 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.
UNSUPPORTED_OPERATION¶
Explanation: This error category is used to signal that an unimplemented code-path has been triggered by a client or participant operator request.
Category: InternalUnsupportedOperation
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status UNIMPLEMENTED without any details for security reasons.
Resolution: This error is caused by a participant node misconfiguration or by an implementation bug. Resolution requires participant operator intervention.
2.2. ParticipantErrorGroup / IndexErrors¶
Errors raised by the Participant Index persistence layer.
2.2.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. It is exposed on the API with grpc-status INTERNAL without any details for 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. It is exposed on the API with grpc-status INTERNAL without any details for 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 and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.
Resolution: Re-submit the request.
2.3. ParticipantErrorGroup / LedgerApiErrors¶
Errors raised by or forwarded by the Ledger API.
HEAP_MEMORY_OVER_LIMIT¶
Explanation: This error happens when the JVM heap memory pool exceeds a pre-configured limit.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: The following actions can be taken: 1. Review the historical use of heap space by inspecting the metric given in the message. 2. Review the current heap space limits configured in the rate limiting configuration. 3. Try to space out requests that are likely to require a large amount of memory to process.
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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: Contact support.
MAXIMUM_NUMBER_OF_STREAMS¶
Explanation: This error happens when the number of concurrent gRPC streaming requests exceeds the configured limit.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: The following actions can be taken: 1. Review the historical need for concurrent streaming by inspecting the metric given in the message. 2. Review the maximum streams limit configured in the rate limiting configuration. 3. Try to space out streaming requests such that they do not need to run in parallel with each other.
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 INFO on the server side and 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.
THREADPOOL_OVERLOADED¶
Explanation: This happens when the rate of submitted gRPC requests requires more CPU or database power than is available.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: The following actions can be taken: Here the ‘queue size’ for the threadpool is considered as reported by the executor itself. 1. Review the historical ‘queue size’ growth by inspecting the metric given in the message. 2. Review the maximum ‘queue size’ limits configured in the rate limiting configuration. 3. Try to space out requests that are likely to require a lot of CPU or database power.
2.3.1. ParticipantErrorGroup / LedgerApiErrors / AdminServices¶
Errors raised by Ledger API admin services.
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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Fetch newest configuration and/or retry.
INTERNALLY_INVALID_KEY¶
Explanation: A cryptographic key used by the configured system is not valid
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Refer to the detailed message of the received error.
2.3.1.1. ParticipantErrorGroup / LedgerApiErrors / AdminServices / IdentityProviderConfigServiceErrorGroup¶
IDP_CONFIG_ALREADY_EXISTS¶
Explanation: There already exists an identity provider configuration with the same identity provider id.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.
Resolution: Check that you are connecting to the right participant node and the identity provider id is spelled correctly, or use an identity provider that already exists.
IDP_CONFIG_BY_ISSUER_NOT_FOUND¶
Explanation: The identity provider config referred to by the request was not found.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.
Resolution: Check that you are connecting to the right participant node and the identity provider config is spelled correctly, or create the configuration.
IDP_CONFIG_ISSUER_ALREADY_EXISTS¶
Explanation: There already exists an identity provider configuration with the same issuer.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.
Resolution: Check that you are connecting to the right participant node and the identity provider id is spelled correctly, or use an identity provider that already exists.
IDP_CONFIG_NOT_FOUND¶
Explanation: The identity provider config referred to by the request was not found.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.
Resolution: Check that you are connecting to the right participant node and the identity provider config is spelled correctly, or create the configuration.
INVALID_IDENTITY_PROVIDER_UPDATE_REQUEST¶
Explanation: There was an attempt to update an identity provider config using an invalid update request.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.
Resolution: Inspect the error details for specific information on what made the request invalid. Retry with an adjusted update request.
TOO_MANY_IDENTITY_PROVIDER_CONFIGS¶
Explanation: A system can have only a limited number of identity provider configurations. There was an attempt to create an identity provider configuration.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Delete some of the already existing identity provider configurations. Contact the participant operator if the limit is too low.
2.3.1.2. ParticipantErrorGroup / LedgerApiErrors / AdminServices / PartyManagementServiceErrorGroup¶
CONCURRENT_PARTY_DETAILS_UPDATE_DETECTED¶
Explanation: Concurrent updates to a party can be controlled by supplying an update request with a resource version (this is optional). A party’s resource version can be obtained by reading the party on the Ledger API. There was attempt to update a party using a stale resource version, indicating that a different process had updated the party earlier.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: Read this party again to obtain its most recent state and in particular its most recent resource version. Use the obtained information to build and send a new update request.
INTERNAL_PARTY_RECORD_ALREADY_EXISTS¶
Explanation: Each on-ledger party known to this participant node can have a participant’s local metadata assigned to it. The local information about a party referred to by this request was found when it should have been not found.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: This error can indicate a problem with the server’s storage or implementation.
INTERNAL_PARTY_RECORD_NOT_FOUND¶
Explanation: Each on-ledger party known to this participant node can have a participant’s local metadata assigned to it. The local information about a party referred to by this request was not found when it should have been found.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: This error can indicate a problem with the server’s storage or implementation.
INVALID_PARTY_DETAILS_UPDATE_REQUEST¶
Explanation: There was an attempt to update a party using an invalid update request.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.
Resolution: Inspect the error details for specific information on what made the request invalid. Retry with an adjusted update request.
MAX_PARTY_DETAILS_ANNOTATIONS_SIZE_EXCEEDED¶
Explanation: A party can have at most 256kb worth of annotations in total measured in number of bytes in UTF-8 encoding. There was an attempt to allocate or update a party such that this limit would have been exceeded.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Retry with fewer annotations or delete some of the party’s existing annotations.
PARTY_NOT_FOUND¶
Explanation: The party referred to by the request was not found.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.
Resolution: Check that you are connecting to the right participant node and that the party is spelled correctly.
2.3.1.3. ParticipantErrorGroup / LedgerApiErrors / AdminServices / UserManagementServiceErrorGroup¶
CONCURRENT_USER_UPDATE_DETECTED¶
Explanation: Concurrent updates to a user can be controlled by supplying an update request with a resource version (this is optional). A user’s resource version can be obtained by reading the user on the Ledger API. There was attempt to update a user using a stale resource version, indicating that a different process had updated the user earlier.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: Read this user again to obtain its most recent state and in particular its most recent resource version. Use the obtained information to build and send a new update request.
INVALID_USER_UPDATE_REQUEST¶
Explanation: There was an attempt to update a user using an invalid update request.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.
Resolution: Inspect the error details for specific information on what made the request invalid. Retry with an adjusted update request.
MAX_USER_ANNOTATIONS_SIZE_EXCEEDED¶
Explanation: A user can have at most 256kb worth of annotations in total measured in number of bytes in UTF-8 encoding. There was an attempt to create or update a user such that this limit would have been exceeded.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Retry with fewer annotations or delete some of the user’s existing annotations.
TOO_MANY_USER_RIGHTS¶
Explanation: A user can have only a limited number of user rights. There was an attempt to create a user with too many rights or grant too many rights to a user.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Retry with a smaller number of rights or delete some of the already existing rights of this user. Contact the participant operator if the limit is too low.
USER_ALREADY_EXISTS¶
Explanation: There already exists a user with the same user-id.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.
Resolution: Check that you are connecting to the right participant node and the user-id is spelled correctly, or use the user that already exists.
USER_NOT_FOUND¶
Explanation: The user referred to by the request was not found.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.
Resolution: Check that you are connecting to the right participant node and the user-id is spelled correctly, if yes, create the user.
2.3.2. ParticipantErrorGroup / LedgerApiErrors / AuthorizationChecks¶
Authentication and authorization 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. It is exposed on the API with grpc-status INTERNAL without any details for 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. It is exposed on the API with grpc-status PERMISSION_DENIED without any details for security reasons.
Resolution: Inspect your command and your token or ask your participant operator for an explanation why this command failed.
STALE_STREAM_AUTHORIZATION¶
Explanation: The stream was aborted because the authenticated user’s rights changed, and the user might thus no longer be authorized to this stream.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: The application should automatically retry fetching the stream. It will either succeed, or fail with an explicit denial of authentication or permission.
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. It is exposed on the API with grpc-status UNAUTHENTICATED without any details for security reasons.
Resolution: Ask your participant operator to provide you with an appropriate JWT token.
2.3.3. 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 and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: Retry the transaction submission.
2.3.3.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 and 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 and 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 and 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 and 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.3.3.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 and 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.3.3.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 and 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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.
Resolution: Contact support.
2.3.3.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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.
Resolution: Inspect error details and correct your application.
2.3.4. 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 and 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.
DISCLOSED_CONTRACT_INVALID¶
Explanation: This error occurs if the disclosed payload or metadata of one of the contracts does not match the actual payload or metadata of the contract.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Re-submit the command using valid disclosed contract payload and metadata.
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 and 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 and 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 and 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 and 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 and 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.
Resolution: Retry the transaction submission.
SUBMISSION_ALREADY_IN_FLIGHT¶
Explanation: Another command submission with the same change ID (application ID, command ID, actAs) is already being processed.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.
Resolution: Listen to the command completion stream until a completion for the in-flight command submission is published. Alternatively, resubmit the command. If the in-flight submission has finished successfully by then, this will return more detailed information about the earlier one. If the in-flight submission has failed by then, the resubmission will attempt to record the new transaction on the ledger.
2.3.5. 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 and 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 and 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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: Inspect the error message and contact support.
2.3.5.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 and 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 and 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 and 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 and 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 and 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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.
Resolution: Inspect the dar and contact support.
2.3.6. 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 and 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 and 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 and 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 and 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 and 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 and 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 and 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 and 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 and 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.3.6.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 and 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 and 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.
TEMPLATES_OR_INTERFACES_NOT_FOUND¶
Explanation: The queried template or interface ids do not exist.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.
Resolution: Use valid template or interface ids in your query or ask the participant operator to upload the package containing the necessary interfaces/templates.
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 and 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.3.7. 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. Since: 1.18.0
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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: Contact support.
OUT_OF_QUOTA¶
Deprecation: Corresponds to transaction submission rejections that are not produced anymore. Since: 1.18.0
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 and 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 and 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. It is exposed on the API with grpc-status PERMISSION_DENIED without any details for 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 and 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.
2.3.7.1. ParticipantErrorGroup / LedgerApiErrors / WriteServiceRejections / 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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: Contact support.
INTERNALLY_INCONSISTENT_KEYS¶
Explanation: The participant didn’t detect an inconsistent key usage in the transaction. Within the transaction, an exercise, fetch or lookupByKey failed because the mapping of key -> contract ID was inconsistent with earlier actions.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.
Resolution: Contact support.