Errors

Each SDK has a custom error type which allows you to get additional details about problems that occur while calling APIs. It has a standard message that can be logged, but it also contains the following useful fields:

1. Code - A ConnectRPC (gRPC) status code that indicates the high level category of the error.
2. StatelyCode - A string that describes a specific error condition. You can check these codes to handle specific error cases. There are constants available in each SDK for the subset of StatelyCodes that we expect users to have to handle. Note that the API may return new StatelyCodes that are not yet covered by the SDK constants.

Language	Custom Error Type	StatelyCode Constants
Go	github.com/StatelyCloud/go-sdk/sdkerror.Error	github.com/StatelyCloud/go-sdk/sdkerror.StatelyErrorCode
TypeScript	StatelyError	ErrorCode
Ruby	StatelyDB::Error	StatelyCode
Python	statelydb.StatelyError	statelydb.StatelyCode

StatelyCode Reference

The following is a non-exhaustive list of error codes that can be returned by the Stately SDKs, and our recommendation for handling it. If you encounter an error code that is not listed here, please let us know.

BackupsUnavailable

Code: Unavailable
BackupsUnavailable indicates that backups are not currently enabled for a Store or that the current environment does not support backups. If this is unexpected, please contact support.

• Retryable

ConcurrentModification

Code: Aborted
ConcurrentModification indicates the current transaction was aborted because of a non-serializable interaction with another transaction was detected, a stale read was detected, or because attempts to resolve an otherwise serializable interaction have exceeded the maximum number of internal resolution retries. Examples:

1. TransactionA and TransactionB are opened concurrently. TransactionA reads ItemX, puts ItemY. Before transactionA can commit, transactionB writes ItemX and commits. When transactionA tries to commit, it will fail with ConcurrentModification because the read of ItemX in transactionA is no longer valid. That is, the data in ItemX which leads to the decision to put ItemY may have changed, and thus a conflict is detected.

2. TransactionA is opened which writes ItemA with an initialValue field (a field used for ID assignment) — the generated ID is returned to the client. transactionB also performs a on an item which resolves to the same initialValue, transactionB is committed first. Since transactionA may have acted on the generatedID (e.g. written in a different record), it will be aborted because the ID is no longer valid for the item it was intended for.

3. A read or list operation detected that underlying data has changed since the transaction began.

• Retryable This error is immediately retryable.

ConditionalCheckFailed

Code: FailedPrecondition
ConditionalCheckFailed indicates that conditions provided to perform an operation were not met. For example, a condition to write an item only if it does not already exist. In the future StatelyDB may provide more information about the failed condition; if this feature is a blocker, please contact support.

• Not Retryable Typically a conditional check failure is not retryable unless the conditions for the operation are changed.

Internal

Code: Internal
This error indicates a bug in StatelyDB. Stately has been notified about this error and will take necessary actions to correct it. If this problem persists, please contact support.

• Not Retryable

InvalidArgument

Code: InvalidArgument
InvalidArgument indicates something in a request was incorrect or missing. The error message returned should provide more information about the specific issue. If this is not sufficient, please contact support.

• Not Retryable

InvalidKeyPath

Code: InvalidArgument
InvalidKeyPath indicates that the provided key path or key IDs are invalid. Key IDs can be strings, positive integers, uuids or bytes. The error message returned should provide more information about the specific issue. If this is not sufficient, please contact support.

• Not Retryable

ItemTypeNotFound

Code: InvalidArgument
ItemTypeNotFound indicates that the ItemType supplied in a Put request was not found in the current schema or that a provided Key does not match the key of an ItemType in schema. Please ensure that a the schema being used has been published via the Stately CLI stately schema put, the client has is using the published version, and that any KeyPaths in use are correctly composed, then try again.

• Not Retryable

MarshalFailure

Code: Internal
MarshalFailure indicates that data transformation failed on our end.

• Not Retryable

NonRecoverableTransaction

Code: FailedPrecondition
NonRecoverableTransaction indicates that conditions required for the transaction to succeed are not possible to meet with the current state of the system. This can occur when an Item has more than one key-path, and is written with a “must not exist” condition (e.g. with ID Generation on one of the keys) but another keys already maps to an existing item in the store. Permitting such a write would result in conflicting state; two independent records with aliases pointing to the same item.

• Not Retryable

NotImplemented

Code: Unimplemented
This error indicates that an operation or feature is not implemented in StatelyDB. Stately has been notified about this error and will take necessary actions to correct it. If this problem persists, please contact support.

• Not Retryable

OrganizationNotFound

Code: NotFound
OrganizationNotFound indicates that an Organization was not found or access to this organization has been denied. Please ensure you have the correct organization ID and permissions. If you believe this is an error, please contact support.

• Not Retryable This is not retryable until the organization is created, or access is granted.

PermissionDenied

Code: PermissionDenied
PermissionDenied is a catch-all indicating that the caller cannot do the requested operation. Typically this is an access restriction on an operation or specific API that permits only specific users or roles to perform the operation. If you believe you should have access, please contact support.

• Not Retryable

ProjectNotFound

Code: NotFound
ProjectNotFound indicates that a Project was not found or access to this project has been denied. Please ensure you have the correct project ID and permissions. If you believe this is an error, please contact support.

• Not Retryable This is not retryable until the project is created, or access is granted.

SchemaNotFound

Code: NotFound
SchemaNotFound indicates that a schema was not found for this store. Schema are required to operate on a store. Please ensure that a schema has been bound via the Stately CLI stately schema bind command, then try again.

• Not Retryable This is not retryable until schema has been published to the store.

SignatureInvalid

Code: InvalidArgument
SignatureInvalid indicates the signature for a signed payload, such as a ListToken’s token_data, did not match its key. This may be due to tampering or corruption. Please do not tamper with opaque tokens. To resolve this it may be necessary to create a new token from the original source; for example by starting a new BeginList operation.

• Not Retryable

StoreInUse

Code: Unavailable
StoreInUse indicates that the underlying Store is currently in being updated and cannot be modified until the operation in progress has completed.

• Retryable This can be retried with backoff.

StoreNotFound

Code: NotFound
The store requested was not found or access to this store has been denied. Please ensure you have the correct store ID and permissions. If you believe this is an error, please contact support.

• Not Retryable This is not retryable until the organization is created, or access is granted.

StoreRequestLimitExceeded

Code: ResourceExhausted
StoreRequestLimitExceeded indicates that an attempt to modify a Store has been temporarily rejected due to exceeding global modification limits. StatelyDB has been notified about this error and will take necessary actions to correct it. In the event that the issue has not been resolved, please contact support.

• Retryable

StoreThroughputExceeded

Code: ResourceExhausted
StoreThroughputExceeded indicates that the underlying Store does not have resources to complete the request. This may indicate a request rate is too high to a specific Group or that a sudden burst of traffic has exceeded a Store’s provisioned capacity.

• Retryable With an exponential backoff.

StreamClosed

Code: FailedPrecondition
StreamClosed indicates that the client or server tried to use a stream which has already closed. This is an unexpected error and may indicate a bug in application code using the stream.

• Not Retryable

TransactionTooLarge

Code: InvalidArgument
TransactionTooLarge indicates that the aggregate size of a transaction is too large. This error is returned when the total number of items to track, including reads, puts, deletes, and updates derived from secondary item KeyPaths or changes to secondary key paths exceeds 100 items. OR when the aggregate size of all items to write (in bytes) exceeds 4MB. The error message returned should provide more information about which case was hit. To resolve this error, please reduce the size of the transaction and try again.

• Not Retryable

Unauthenticated

Code: Unauthenticated
Unauthenticated is returned whenever an authentication token is missing or malformed. This error can be resolved by logging in and/or refreshing a token. In most SDK clients, this error can be automatically resolved by retrying a request or manually refreshing a token token. In the CLI this error can be resolved by running stately login.

• Not Retryable

Unknown

Code: Unknown
This error indicates that an unknown error occurred.

• Not Retryable

UserAlreadyExists

Code: AlreadyExists
UserAlreadyExists indicates that an attempt to create a user failed because a user with a given oauth subject has already been created. If you believe this is an error, please contact support.

• Not Retryable

UserNotFound

Code: PermissionDenied
UserNotfound indicates that a caller does not exist in system or the caller does not have access to the requested resource. If you are sure that this user exists that this user exists and that you should have access, please contact support.

• Not Retryable

UserNotFoundForWhoami

Code: NotFound
UserNotFoundForWhoami is only returned from the whoami endpoint. It indicates that Stately has no record of the the user. This can often be fixed by simply logging into https://console.stately.cloud to trigger a refresh. If that fails, please contact support.

• Not Retryable Not until the user has been created.

WrongRegion

Code: InvalidArgument
WrongRegion indicates that the request involved a store that lives in a different region than the API you called. Please make sure to call the API endpoint that matches the region of your store.

• Not Retryable