Error codes · DynamoDB in C#

Handling errors

Every error an ARX call throws is an ArxException with a stable Code: the same number and name in every provider. Its message starts with it (ARX3001 UniqueViolation: …), and the thousands digit is its Category. Catch by code, by category, or by IsTransient to retry, always on the base class: catch (ArxException e) when (e.Code == ArxErrorCode.RecordNotFound). Some codes come as a subclass (ArxValidationException before the database, ArxDatabaseException from it), but not every one, so a catch of a subclass can miss an error. A misuse found while you build the schema catalog at startup (a table declared twice, a key of a table that isn't declared) is an ArgumentException, as .NET builders report one, and a null argument an ArgumentNullException. The Errors in practice guide covers retries, HTTP statuses and a first connection's errors. The database's own error stays on the exception: SqlState, and the driver's exception as InnerException.

Catch the errors a create meetsCreate
Catch an injection attemptCreate
Catch an injection attemptUpdate
Catch an injection attemptDelete
Catch an injection attemptRetrieveMultiple

ARX1xxx Validation

ARX refused the call before sending it: invalid input, a misused connection, transaction or batch scope, or a name that looks like SQL injection.

Code	Meaning	Retry	From Amazon DynamoDB
ARX1001`InvalidArgument`	Invalid input not covered by a more specific code. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1002`MissingEntityName`	The entity name is null or blank. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1003`InvalidIdentifier`	An entity or attribute name fails the identifier rules. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1004`DuplicateAttribute`	The same attribute appears more than once (names are case-insensitive). No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1005`InvalidLookup`	A lookup (`ArxEntityReference`) has no usable Id. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1006`InvalidSelectionSet`	A selection set value has no option set name. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1007`UnsupportedValueType`	An attribute value has a type the provider can't write. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1008`InvalidConnection`	The connection or transaction is of the wrong driver type, or the service has no connection string. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1009`TransactionMismatch`	The transaction belongs to a different connection. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1010`TransactionCompleted`	The transaction has already been committed, rolled back or disposed. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1011`SelectionSetValueNotAllowed`	A selection set value isn't allowed by its set in the catalog: not one of its options, of the wrong kind, a retired option, several values for a single-choice set, a duplicate, or a value the set's storage can't hold. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1012`UnknownSelectionSet`	A selection set value names a set that isn't in the catalog, or no catalog was supplied. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1013`InvalidDateTimeValue`	A date or time value that would be stored as something else than the caller meant: default(DateTime), default(DateTimeOffset) or default(DateOnly) (no real date: a database would store a sentinel or refuse it), or an array mixing UTC and Unspecified DateTime values. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1014`BatchScopeBusy`	A batch scope was called while another call on it was still running. A scope holds one connection, which runs one command at a time: await each call before the next. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1015`TransactionAborted`	A call or a commit on a transaction that an earlier failed call has aborted. The database has already discarded the transaction's work; it can only be rolled back. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1016`IdNotDeclared`	The entity's table isn't declared in the service's schema catalog, and the entity doesn't declare its own id column. A service with a catalog uses only what is declared: ARX doesn't guess an id column. A service created without a catalog reads the table's primary key instead (where the provider can), and raises `TableNotResolvable` when it can't. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1017`SuspectedInjection`	A name (entity, attribute, match column or type) contains SQL syntax: a quote, a statement separator, a comment marker, a bracket, an operator or an SQL keyword after a space. That is the shape of an SQL injection attempt, not of a typo, so it gets its own code to alert on. Refused before the database: nothing was sent. Values are never checked for this: they are always parameters, and any text is stored as typed. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1018`NotPreloaded`	The service is `Strict` and the call names a table or column that wasn't preloaded: refused before the database. Preload it, or turn Strict off. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX1019`TableNotResolvable`	A service without a schema catalog resolves each table from the database, and this table has no id the call can use: no primary key, a primary key of several columns, or one of a type ARX can't use as an id. Refused before anything is sent, only for a call that needs the id (Create, Retrieve, Update or Delete by id). Declare the table in a schema catalog (`ArxIdColumn.NoIdColumn`), or match by a key or columns. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX

ARX2xxx NotFound

The rows the call addressed weren't found as asked: none, several where one was required, or one at another version than the call carried (ARX2004). Nothing was changed.

Code	Meaning	Retry	From Amazon DynamoDB
ARX2002`RecordNotFound`	The record addressed by key doesn't exist.	No	`ConditionalCheckFailed (ARX's condition)` an update whose item doesn't exist: ARX writes the update on condition that it does
ARX2003`MultipleRecordsMatched`	An update or delete with `RequireSingleRow` found more than one row for an entity. Nothing was changed. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX2004`RecordChanged`	The record was changed since it was read: an Update or Delete carried a version (optimistic concurrency) that isn't the record's any more. Nothing was changed: read it again, and apply the change to what is there now. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX

ARX3xxx Constraint

The database refused the change because of a rule: a unique key, a foreign key, NOT NULL, CHECK, or a routine's own error.

Code	Meaning	Retry	From Amazon DynamoDB
ARX3001`UniqueViolation`	A unique constraint or key was violated.	No	`ConditionalCheckFailedException` a create's "doesn't exist yet" condition failed: an item with the key exists (ARX2002 for an update's "exists" condition) `TransactionCanceledException` a transaction was cancelled: mapped by its first reason (a failed condition, a conflict, throttling)
ARX3002`ForeignKeyViolation`	A referenced record is missing, or a record is still referenced. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX3003`NotNullViolation`	A required attribute has no value. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX3004`CheckViolation`	A check constraint or validation rule failed. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX3005`RaisedByDatabase`	A routine the database runs (a procedure or function) refused the call on purpose (PostgreSQL `RAISE EXCEPTION`, SQL Server `THROW`, MySQL `SIGNAL`). On PostgreSQL: `RAISE EXCEPTION` (SQLSTATE P0001), an `ASSERT` or a state of the routine's own (`USING ERRCODE = 'AX001'`). The message is the routine's; `SqlState`, `Detail` and `Hint` are its own. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX

ARX4xxx Data

A value doesn't fit its column: out of range, too long, in the wrong format or of the wrong type.

Code	Meaning	Retry	From Amazon DynamoDB
ARX4001`ValueOutOfRange`	A number is outside the column's range. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX4002`ValueTooLong`	Text or binary data is longer than the column allows.	No	`ItemCollectionSizeLimitExceededException` an item collection is larger than 10 GB (local secondary index)
ARX4003`InvalidValueFormat`	A value can't be parsed for its column (for example invalid JSON, dates or encoding).	No	`ValidationException` a request DynamoDB refuses: an item over 400 KB is ARX4002, a number out of range ARX4001
ARX4004`DataTypeMismatch`	A value's type doesn't fit the column. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX

ARX5xxx Schema

A table or column doesn't exist, or a declaration in the schema catalog doesn't match the table.

Code	Meaning	Retry	From Amazon DynamoDB
ARX5001`UndefinedEntity`	The table or collection doesn't exist.	No	`ResourceNotFoundException` the table or index doesn't exist
ARX5002`UndefinedAttribute`	The column doesn't exist or can't be written. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX
ARX5003`SchemaMismatch`	A declaration in the schema catalog doesn't match the table: the database returned an id of another type, or `ValidateSchemaAsync` found a difference. The exception says whether rows were stored. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	No	ARX

ARX6xxx Permission

The database user isn't allowed to do it.

Code	Meaning	Retry	From Amazon DynamoDB
ARX6001`PermissionDenied`	The database user lacks the required permission.	No	`AccessDeniedException` the credentials lack a permission `MissingAuthenticationTokenException` the request isn't signed `UnrecognizedClientException` the credentials aren't valid

ARX7xxx Transient

A temporary failure: a deadlock, a conflict, a timeout, throttling or a lost connection. Safe to retry the whole operation (IsTransient is true).

Code	Meaning	Retry	From Amazon DynamoDB
ARX7001`Deadlock`	The operation was chosen as a deadlock victim. Safe to retry. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	Safe to retry	ARX
ARX7002`SerializationFailure`	The operation conflicted with a concurrent transaction. Safe to retry.	Safe to retry	`TransactionConflictException` another transaction is writing the same item `TransactionInProgressException` a transaction with the same client token is still running
ARX7003`Timeout`	The command or a lock wait timed out. Safe to retry. No Amazon DynamoDB error maps to it: ARX raises it itself, from its own checks (before the call, or from what the database returned).	Safe to retry	ARX
ARX7004`Throttled`	The server is rate-limiting or out of connections. Safe to retry later.	Safe to retry	`LimitExceededException` too many control-plane operations at once `ProvisionedThroughputExceededException` the table's provisioned capacity is exceeded `RequestLimitExceeded` the account's request limit is exceeded `ThrottlingException` requests are being throttled
ARX7005`ConnectionFailure`	The database couldn't be reached, or the connection dropped. Safe to retry.	Safe to retry	`InternalServerError` DynamoDB failed internally (retry) `SDK` the SDK couldn't reach the endpoint, or timed out `ServiceUnavailable` DynamoDB is unavailable (retry)

ARX8xxx NotSupported

The provider can't do what was asked, and refuses it rather than ignoring part of it.

Code	Meaning	Retry	From Amazon DynamoDB
ARX8001`NotSupported`	The provider doesn't support the requested operation or feature.	No	`ARX` what DynamoDB can't do: a query without its partition key (unless a scan is allowed), a page number, a total count, more than 100 writes in one transaction, a match that isn't the key, Execute

ARX9xxx Provider

A database error ARX doesn't map; the exception keeps its native code and SQLSTATE.

Code	Meaning	Retry	From Amazon DynamoDB
ARX9001`ProviderError`	A native error the provider doesn't map; see NativeCode and SqlState.	No	any other SQLSTATE