Skip to content
QuantCDN

Run 1 to 25 operations as one transaction

POST
/api/v2/organizations/{organization}/projects/{project}/kv/{store_id}/transact
curl --request POST \
  --url https://dashboard.quantcdn.io/api/v2/organizations/test-org/projects/test-project/kv/test-org-test-project-orders/transact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "idempotencyKey": "checkout-1001", "operations": [ { "type": "check", "key": "stock:sku-1", "version": "01JB2Z6V8Q3M4N5P6R7S8T9V0W" }, { "type": "increment", "key": "stock:sku-1", "amount": -1 } ] }'

Format 2 stores only. Runs 1 to 25 operations on different keys as one transaction: all or none. check: version. set: value, secret, ttl (60 to 31,536,000 s), ifAbsent, ifVersion. delete: ifVersion. increment: amount. Any other field fails VALIDATION. A failed condition is 409 CONFLICT with operation (its index) and reason. With idempotencyKey, a repeat of the same operations within 24 hours returns the first result with replayed true. A lost connection is 503 UNAVAILABLE: retryable is true only when the request has idempotencyKey, and then retry only with the same idempotencyKey; without it the outcome is unknown (retryable false).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organization
required
string

Organization identifier

Example
test-org
project
required
string

Project identifier

Example
test-project
store_id
required
string

KV store id, as returned by KV_list

Example
test-org-test-project-orders

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
idempotencyKey

A repeat of the same operations within 24 hours returns the first result with replayed true; other operations with the same key fail VALIDATION. Send it to make a lost-connection 503 retryable.

string
/^[A-Za-z0-9_-]{1,64}$/
operations
required

1 to 25 operations on different keys. More than 25 is 400 LIMIT_EXCEEDED.

Array<object>
>= 1 items <= 25 items

Each type takes only its own fields. check: version. set: value, secret, ttl, ifAbsent, ifVersion. delete: ifVersion. increment: amount (no ttl). Any other field fails VALIDATION.

object
type
required
string
Allowed values: check set delete increment
key
required
string
version

Check only: the key must have this version and not be expired.

string
/^[0-9A-HJKMNP-TV-Z]{26}$/
value

Set only. Any JSON value.

secret

Set only. Encrypt the value.

boolean
ttl

Set only. Seconds (60 to 31,536,000).

integer
>= 60 <= 31536000
ifAbsent

Set only.

boolean
ifVersion

Set and delete.

string
/^[0-9A-HJKMNP-TV-Z]{26}$/
amount

Increment only. Nonzero.

integer format: int64
default: 1
Example
{
  "type": "set",
  "key": "order:1001",
  "value": {
    "status": "paid"
  },
  "ifVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}
Example
{
  "idempotencyKey": "checkout-1001",
  "operations": [
    {
      "type": "check",
      "key": "stock:sku-1",
      "version": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
    },
    {
      "type": "increment",
      "key": "stock:sku-1",
      "amount": -1
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Applied (replayed true: applied by an earlier request with the same idempotencyKey).

Media typeapplication/json
object
conditional
required
boolean
versions
required

The new version of each set and increment key.

object
key
additional properties
string
replayed

True when an earlier request with the same idempotencyKey applied the operations.

boolean
Example
{
  "conditional": true,
  "versions": {
    "stock:sku-1": "01JB2Z6V8Q3M4N5P6R7S8T9V0X"
  }
}

400

Section titled “400”

Invalid request: VALIDATION, LIMIT_EXCEEDED, CURSOR_INVALID, REQUIRES_FORMAT_2 and the route-specific 400 codes.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code status retryable meaning
VALIDATION 400 false The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED 400 false A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID 400 false The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2 400 false The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED 400 false An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL 400 false A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE 400 false A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND 400 false This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED 400 false The ledger needs a subject field in each entry.
LEDGER_DIRECTION 400 false A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED 400 false confirm is missing or does not equal the store name.
SCOPE_REQUIRED 403 false The token does not list the scope that the route needs.
PERMISSION_DENIED 403 false The role of the token user does not have the permission.
FORBIDDEN 403 false The store is a system store and cannot be purged.
KEY_NOT_FOUND 404 false The key does not exist or has expired.
STORE_NOT_FOUND 404 false The store does not exist or is not in this project.
EXPORT_NOT_FOUND 404 false The store has no export.
LEDGER_NOT_FOUND 404 false The ledger does not exist.
SUBJECT_NOT_FOUND 404 false The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND 404 false The verification run does not exist.
SHRED_NOT_FOUND 404 false The erasure record does not exist.
INDEX_NOT_FOUND 404 false The index does not exist.
NOT_FOUND 404 false No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT 409 false The upgrade action is not valid in the current upgrade state.
CONFLICT 409 false A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION 409 false A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS 409 false An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY 409 false The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED 409 false The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT 409 false A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED 409 false The store name is held by a retained ledger archive.
LEDGER_FORKED 409 false The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED 409 false The ledger was dropped.
LEDGER_FORMAT_RETIRED 409 false The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED 409 false The store still exists. Delete the store first.
ARCHIVE_RETAINED 409 false The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS 409 false Another purge of the store is running. See purgeId.
PURGE_BLOCKED 409 false The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE 409 false The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED 409 true The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION 409 true Another write changed the same data at the same time. Send again.
INDEX_NOT_READY 409 true The index is still building. Send again later.
LEDGER_NOT_READY 409 true The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED 429 true Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL 500 false The KV service failed. No detail is given.
STORE_MIGRATING 503 true The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE 503 true (false when the outcome of a write is unknown) The KV service did not answer. With retryable false, read the data before you send the write again.
object
error
required

Always true.

boolean
message
required
string
code
required
string
Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE
retryable
required

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string
reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string
Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead
retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string
Allowed values: not_dropped not_drained
hint

What to do next, when the KV service gives a hint.

string
state

The current state of the store, index, ledger or export, when the error names it.

string
Example
{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

403

Section titled “403”

SCOPE_REQUIRED (the token does not list the scope) or PERMISSION_DENIED (the role does not have the permission).

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code status retryable meaning
VALIDATION 400 false The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED 400 false A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID 400 false The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2 400 false The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED 400 false An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL 400 false A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE 400 false A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND 400 false This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED 400 false The ledger needs a subject field in each entry.
LEDGER_DIRECTION 400 false A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED 400 false confirm is missing or does not equal the store name.
SCOPE_REQUIRED 403 false The token does not list the scope that the route needs.
PERMISSION_DENIED 403 false The role of the token user does not have the permission.
FORBIDDEN 403 false The store is a system store and cannot be purged.
KEY_NOT_FOUND 404 false The key does not exist or has expired.
STORE_NOT_FOUND 404 false The store does not exist or is not in this project.
EXPORT_NOT_FOUND 404 false The store has no export.
LEDGER_NOT_FOUND 404 false The ledger does not exist.
SUBJECT_NOT_FOUND 404 false The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND 404 false The verification run does not exist.
SHRED_NOT_FOUND 404 false The erasure record does not exist.
INDEX_NOT_FOUND 404 false The index does not exist.
NOT_FOUND 404 false No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT 409 false The upgrade action is not valid in the current upgrade state.
CONFLICT 409 false A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION 409 false A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS 409 false An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY 409 false The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED 409 false The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT 409 false A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED 409 false The store name is held by a retained ledger archive.
LEDGER_FORKED 409 false The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED 409 false The ledger was dropped.
LEDGER_FORMAT_RETIRED 409 false The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED 409 false The store still exists. Delete the store first.
ARCHIVE_RETAINED 409 false The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS 409 false Another purge of the store is running. See purgeId.
PURGE_BLOCKED 409 false The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE 409 false The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED 409 true The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION 409 true Another write changed the same data at the same time. Send again.
INDEX_NOT_READY 409 true The index is still building. Send again later.
LEDGER_NOT_READY 409 true The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED 429 true Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL 500 false The KV service failed. No detail is given.
STORE_MIGRATING 503 true The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE 503 true (false when the outcome of a write is unknown) The KV service did not answer. With retryable false, read the data before you send the write again.
object
error
required

Always true.

boolean
message
required
string
code
required
string
Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE
retryable
required

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string
reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string
Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead
retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string
Allowed values: not_dropped not_drained
hint

What to do next, when the KV service gives a hint.

string
state

The current state of the store, index, ledger or export, when the error names it.

string
Example
{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

404

Section titled “404”

STORE_NOT_FOUND: the store does not exist or is not in this project.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code status retryable meaning
VALIDATION 400 false The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED 400 false A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID 400 false The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2 400 false The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED 400 false An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL 400 false A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE 400 false A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND 400 false This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED 400 false The ledger needs a subject field in each entry.
LEDGER_DIRECTION 400 false A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED 400 false confirm is missing or does not equal the store name.
SCOPE_REQUIRED 403 false The token does not list the scope that the route needs.
PERMISSION_DENIED 403 false The role of the token user does not have the permission.
FORBIDDEN 403 false The store is a system store and cannot be purged.
KEY_NOT_FOUND 404 false The key does not exist or has expired.
STORE_NOT_FOUND 404 false The store does not exist or is not in this project.
EXPORT_NOT_FOUND 404 false The store has no export.
LEDGER_NOT_FOUND 404 false The ledger does not exist.
SUBJECT_NOT_FOUND 404 false The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND 404 false The verification run does not exist.
SHRED_NOT_FOUND 404 false The erasure record does not exist.
INDEX_NOT_FOUND 404 false The index does not exist.
NOT_FOUND 404 false No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT 409 false The upgrade action is not valid in the current upgrade state.
CONFLICT 409 false A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION 409 false A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS 409 false An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY 409 false The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED 409 false The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT 409 false A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED 409 false The store name is held by a retained ledger archive.
LEDGER_FORKED 409 false The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED 409 false The ledger was dropped.
LEDGER_FORMAT_RETIRED 409 false The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED 409 false The store still exists. Delete the store first.
ARCHIVE_RETAINED 409 false The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS 409 false Another purge of the store is running. See purgeId.
PURGE_BLOCKED 409 false The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE 409 false The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED 409 true The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION 409 true Another write changed the same data at the same time. Send again.
INDEX_NOT_READY 409 true The index is still building. Send again later.
LEDGER_NOT_READY 409 true The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED 429 true Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL 500 false The KV service failed. No detail is given.
STORE_MIGRATING 503 true The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE 503 true (false when the outcome of a write is unknown) The KV service did not answer. With retryable false, read the data before you send the write again.
object
error
required

Always true.

boolean
message
required
string
code
required
string
Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE
retryable
required

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string
reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string
Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead
retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string
Allowed values: not_dropped not_drained
hint

What to do next, when the KV service gives a hint.

string
state

The current state of the store, index, ledger or export, when the error names it.

string
Example
{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

409

Section titled “409”

CONFLICT, UNIQUE_VIOLATION, UPGRADE_CONFLICT, EXPORT_IN_PROGRESS, the LEDGER_* conflicts and the archive purge conflicts STORE_NOT_DELETED, ARCHIVE_RETAINED, PURGE_IN_PROGRESS, PURGE_BLOCKED and PURGE_NOT_COMPLETE (not retryable); CONTENTION, INDEX_NOT_READY, LEDGER_NOT_READY and DIGEST_OWED (retryable).

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code status retryable meaning
VALIDATION 400 false The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED 400 false A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID 400 false The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2 400 false The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED 400 false An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL 400 false A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE 400 false A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND 400 false This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED 400 false The ledger needs a subject field in each entry.
LEDGER_DIRECTION 400 false A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED 400 false confirm is missing or does not equal the store name.
SCOPE_REQUIRED 403 false The token does not list the scope that the route needs.
PERMISSION_DENIED 403 false The role of the token user does not have the permission.
FORBIDDEN 403 false The store is a system store and cannot be purged.
KEY_NOT_FOUND 404 false The key does not exist or has expired.
STORE_NOT_FOUND 404 false The store does not exist or is not in this project.
EXPORT_NOT_FOUND 404 false The store has no export.
LEDGER_NOT_FOUND 404 false The ledger does not exist.
SUBJECT_NOT_FOUND 404 false The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND 404 false The verification run does not exist.
SHRED_NOT_FOUND 404 false The erasure record does not exist.
INDEX_NOT_FOUND 404 false The index does not exist.
NOT_FOUND 404 false No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT 409 false The upgrade action is not valid in the current upgrade state.
CONFLICT 409 false A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION 409 false A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS 409 false An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY 409 false The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED 409 false The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT 409 false A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED 409 false The store name is held by a retained ledger archive.
LEDGER_FORKED 409 false The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED 409 false The ledger was dropped.
LEDGER_FORMAT_RETIRED 409 false The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED 409 false The store still exists. Delete the store first.
ARCHIVE_RETAINED 409 false The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS 409 false Another purge of the store is running. See purgeId.
PURGE_BLOCKED 409 false The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE 409 false The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED 409 true The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION 409 true Another write changed the same data at the same time. Send again.
INDEX_NOT_READY 409 true The index is still building. Send again later.
LEDGER_NOT_READY 409 true The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED 429 true Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL 500 false The KV service failed. No detail is given.
STORE_MIGRATING 503 true The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE 503 true (false when the outcome of a write is unknown) The KV service did not answer. With retryable false, read the data before you send the write again.
object
error
required

Always true.

boolean
message
required
string
code
required
string
Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE
retryable
required

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string
reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string
Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead
retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string
Allowed values: not_dropped not_drained
hint

What to do next, when the KV service gives a hint.

string
state

The current state of the store, index, ledger or export, when the error names it.

string
Example
{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

429

Section titled “429”

RATE_LIMITED (retryable): a rate limit is used up. The limits are the per-token limit (api-token, default 240 requests per minute per token and organisation) and, on some operations, the per-project KV limits (kv-admin 10, kv-erase 30, kv-verify 6 requests per minute). Wait for Retry-After seconds, then send the request again. See Rate limits in the API description.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code status retryable meaning
VALIDATION 400 false The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED 400 false A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID 400 false The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2 400 false The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED 400 false An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL 400 false A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE 400 false A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND 400 false This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED 400 false The ledger needs a subject field in each entry.
LEDGER_DIRECTION 400 false A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED 400 false confirm is missing or does not equal the store name.
SCOPE_REQUIRED 403 false The token does not list the scope that the route needs.
PERMISSION_DENIED 403 false The role of the token user does not have the permission.
FORBIDDEN 403 false The store is a system store and cannot be purged.
KEY_NOT_FOUND 404 false The key does not exist or has expired.
STORE_NOT_FOUND 404 false The store does not exist or is not in this project.
EXPORT_NOT_FOUND 404 false The store has no export.
LEDGER_NOT_FOUND 404 false The ledger does not exist.
SUBJECT_NOT_FOUND 404 false The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND 404 false The verification run does not exist.
SHRED_NOT_FOUND 404 false The erasure record does not exist.
INDEX_NOT_FOUND 404 false The index does not exist.
NOT_FOUND 404 false No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT 409 false The upgrade action is not valid in the current upgrade state.
CONFLICT 409 false A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION 409 false A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS 409 false An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY 409 false The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED 409 false The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT 409 false A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED 409 false The store name is held by a retained ledger archive.
LEDGER_FORKED 409 false The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED 409 false The ledger was dropped.
LEDGER_FORMAT_RETIRED 409 false The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED 409 false The store still exists. Delete the store first.
ARCHIVE_RETAINED 409 false The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS 409 false Another purge of the store is running. See purgeId.
PURGE_BLOCKED 409 false The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE 409 false The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED 409 true The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION 409 true Another write changed the same data at the same time. Send again.
INDEX_NOT_READY 409 true The index is still building. Send again later.
LEDGER_NOT_READY 409 true The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED 429 true Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL 500 false The KV service failed. No detail is given.
STORE_MIGRATING 503 true The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE 503 true (false when the outcome of a write is unknown) The KV service did not answer. With retryable false, read the data before you send the write again.
object
error
required

Always true.

boolean
message
required
string
code
required
string
Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE
retryable
required

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string
reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string
Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead
retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string
Allowed values: not_dropped not_drained
hint

What to do next, when the KV service gives a hint.

string
state

The current state of the store, index, ledger or export, when the error names it.

string
Example
{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before the next request.

RateLimit-Limit
integer
>= 1

The request limit of the window (IETF draft). X-RateLimit-Limit carries the same value.

RateLimit-Remaining
integer

Requests left in the window: 0 on a 429 (IETF draft). X-RateLimit-Remaining carries the same value.

RateLimit-Reset
integer

Seconds until the window resets (IETF draft). X-RateLimit-Reset is the same moment as a Unix timestamp.

500

Section titled “500”

INTERNAL: the KV service failed. No detail is given.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code status retryable meaning
VALIDATION 400 false The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED 400 false A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID 400 false The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2 400 false The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED 400 false An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL 400 false A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE 400 false A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND 400 false This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED 400 false The ledger needs a subject field in each entry.
LEDGER_DIRECTION 400 false A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED 400 false confirm is missing or does not equal the store name.
SCOPE_REQUIRED 403 false The token does not list the scope that the route needs.
PERMISSION_DENIED 403 false The role of the token user does not have the permission.
FORBIDDEN 403 false The store is a system store and cannot be purged.
KEY_NOT_FOUND 404 false The key does not exist or has expired.
STORE_NOT_FOUND 404 false The store does not exist or is not in this project.
EXPORT_NOT_FOUND 404 false The store has no export.
LEDGER_NOT_FOUND 404 false The ledger does not exist.
SUBJECT_NOT_FOUND 404 false The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND 404 false The verification run does not exist.
SHRED_NOT_FOUND 404 false The erasure record does not exist.
INDEX_NOT_FOUND 404 false The index does not exist.
NOT_FOUND 404 false No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT 409 false The upgrade action is not valid in the current upgrade state.
CONFLICT 409 false A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION 409 false A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS 409 false An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY 409 false The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED 409 false The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT 409 false A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED 409 false The store name is held by a retained ledger archive.
LEDGER_FORKED 409 false The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED 409 false The ledger was dropped.
LEDGER_FORMAT_RETIRED 409 false The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED 409 false The store still exists. Delete the store first.
ARCHIVE_RETAINED 409 false The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS 409 false Another purge of the store is running. See purgeId.
PURGE_BLOCKED 409 false The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE 409 false The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED 409 true The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION 409 true Another write changed the same data at the same time. Send again.
INDEX_NOT_READY 409 true The index is still building. Send again later.
LEDGER_NOT_READY 409 true The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED 429 true Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL 500 false The KV service failed. No detail is given.
STORE_MIGRATING 503 true The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE 503 true (false when the outcome of a write is unknown) The KV service did not answer. With retryable false, read the data before you send the write again.
object
error
required

Always true.

boolean
message
required
string
code
required
string
Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE
retryable
required

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string
reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string
Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead
retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string
Allowed values: not_dropped not_drained
hint

What to do next, when the KV service gives a hint.

string
state

The current state of the store, index, ledger or export, when the error names it.

string
Example
{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

503

Section titled “503”

STORE_MIGRATING (retryable, Retry-After) or UNAVAILABLE. UNAVAILABLE with retryable true (for example a new store whose table is still being created, with Retry-After 5) is safe to retry with backoff; honour Retry-After. With retryable false the outcome of a write is unknown: read before you write again.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code status retryable meaning
VALIDATION 400 false The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED 400 false A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID 400 false The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2 400 false The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED 400 false An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL 400 false A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE 400 false A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND 400 false This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED 400 false The ledger needs a subject field in each entry.
LEDGER_DIRECTION 400 false A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED 400 false confirm is missing or does not equal the store name.
SCOPE_REQUIRED 403 false The token does not list the scope that the route needs.
PERMISSION_DENIED 403 false The role of the token user does not have the permission.
FORBIDDEN 403 false The store is a system store and cannot be purged.
KEY_NOT_FOUND 404 false The key does not exist or has expired.
STORE_NOT_FOUND 404 false The store does not exist or is not in this project.
EXPORT_NOT_FOUND 404 false The store has no export.
LEDGER_NOT_FOUND 404 false The ledger does not exist.
SUBJECT_NOT_FOUND 404 false The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND 404 false The verification run does not exist.
SHRED_NOT_FOUND 404 false The erasure record does not exist.
INDEX_NOT_FOUND 404 false The index does not exist.
NOT_FOUND 404 false No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT 409 false The upgrade action is not valid in the current upgrade state.
CONFLICT 409 false A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION 409 false A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS 409 false An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY 409 false The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED 409 false The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT 409 false A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED 409 false The store name is held by a retained ledger archive.
LEDGER_FORKED 409 false The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED 409 false The ledger was dropped.
LEDGER_FORMAT_RETIRED 409 false The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED 409 false The store still exists. Delete the store first.
ARCHIVE_RETAINED 409 false The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS 409 false Another purge of the store is running. See purgeId.
PURGE_BLOCKED 409 false The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE 409 false The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED 409 true The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION 409 true Another write changed the same data at the same time. Send again.
INDEX_NOT_READY 409 true The index is still building. Send again later.
LEDGER_NOT_READY 409 true The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED 429 true Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL 500 false The KV service failed. No detail is given.
STORE_MIGRATING 503 true The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE 503 true (false when the outcome of a write is unknown) The KV service did not answer. With retryable false, read the data before you send the write again.
object
error
required

Always true.

boolean
message
required
string
code
required
string
Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE
retryable
required

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string
reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string
Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead
retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string
Allowed values: not_dropped not_drained
hint

What to do next, when the KV service gives a hint.

string
state

The current state of the store, index, ledger or export, when the error names it.

string
Example
{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

Headers

Section titled “Headers”
Retry-After
integer