Skip to content
QuantCDN

Get the signed receipt of a shred

GET
/api/v2/organizations/{organization}/projects/{project}/kv/{store_id}/ledgers/{ledger_name}/shreds/{shred_id}/receipt
curl --request GET \
  --url https://dashboard.quantcdn.io/api/v2/organizations/test-org/projects/test-project/kv/test-org-test-project-orders/ledgers/aiUse/shreds/01JB2Z6V8Q3M4N5P6R7S8T9V0W/receipt \
  --header 'Authorization: Bearer <token>'

The receipt of an erasure, signed with the ledger key (ECDSA P-256 over the SHA-256 of its JCS bytes). It is the same receipt as the shred answer’s: signed once, stored, never signed again. It names the subject by subjectRef, never by the id. entryCount and entriesSha256 bind the shred entries; entries is left out when the receipt would pass 300 KB (then KV_ledgers_shreds_entries serves them). The body is returned byte for byte: save the whole answer and check it offline with kv-ledger-verify verify-signed and the public key (KV_ledgers_public_key), with –entries for a receipt without the list.\n\nNeeds kv:ledger:read and the ledger_read permission.

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
ledger_name
required
string
/^[A-Za-z][A-Za-z0-9_]{0,63}$/
Example
aiUse
shred_id
required
string
/^[0-9A-HJKMNP-TV-Z]{26}$/

The shredId of a shred answer, or the id of an erasure record (KV_ledgers_shreds_list). A ULID.

Example
01JB2Z6V8Q3M4N5P6R7S8T9V0W

Responses

Section titled “Responses”

200

Section titled “200”

The signed receipt, byte for byte.

Media typeapplication/json

The signed receipt with its parsed copy.

object
json
required

The RFC 8785 (JCS) text of the receipt that was signed.

string
signature
required

Base64 DER ECDSA P-256 signature over the SHA-256 of the UTF-8 bytes of json.

string
keyId
required

The KMS key ARN of the ledger key.

string
algorithm
required
string
Allowed values: ECDSA_SHA_256
receipt
required

The parsed form of json (a convenience copy; only json is signed).

object
v
required
integer
Allowed values: 2
type
required
string
Allowed values: kv-ledger-shred-receipt
id
required

The shredId.

string
org
required
string
store
required
string
ledger
required
string
subjectRef
required
string
/^[0-9a-f]{32}$/
refKeyVersion
required

The version of the reference key that made subjectRef.

integer
>= 1
shreddedAt
required
string format: date-time
fullyErasedAfter
required
string format: date-time
reason
required
string
authority
required
string
requestedBy
required
string
entryCount
required

The number of shred entries (0 for a forked store or a DROPPED ledger).

integer
entriesSha256
required

SHA-256 (hex) of the JCS of the shred entries, sorted by key.

string
/^[0-9a-f]{64}$/
entries

Left out when the receipt would pass 300 KB: then KV_ledgers_shreds_entries serves them.

Array<object>
object
key
required

The entry key, :.

string
shard
required
string
seq
required
integer
hash
required
string
ledgerForked
boolean
supersedes

The id of the forked record that this re-shred supersedes.

string
Example
{
  "algorithm": "ECDSA_SHA_256",
  "receipt": {
    "v": 2,
    "type": "kv-ledger-shred-receipt",
    "ledgerForked": true
  }
}

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”

KEY_NOT_FOUND, STORE_NOT_FOUND, LEDGER_NOT_FOUND, SUBJECT_NOT_FOUND, EXPORT_NOT_FOUND, VERIFICATION_NOT_FOUND, SHRED_NOT_FOUND, INDEX_NOT_FOUND or NOT_FOUND (no archive, tombstone or purge).

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