Install

Errors ​

Every error has the same body, and a stable code that clients branch on:

json
{ "error": { "code": "unknown_collection", "message": "unknown_collection: calls" } }
  • code is part of the contract: it changes only in a major release.
  • message is for people. Do not parse it.
  • The HTTP status follows the code (table below). A write that matches nothing is not an error: it is 200 with "matched": 0.
  • A _watch stream that already started reports an error as a line {"error":{"code","message"}}, then ends.

The SDKs turn each code into a typed error: Go ndb.ErrUnknownCollection (errors.Is), Ruby Ndb::UnknownCollection, TypeScript UnknownCollectionError.

CodeHTTPMeaning
invalid_request400Bad body: not JSON, unknown key, empty docs, a bad option.
invalid_query400Bad query, sort, operator, date math or key.
invalid_pipeline400Bad aggregate pipeline.
cursor_invalid400The after token is broken.
cursor_mismatch400The token was made for another query, sort or pattern.
cursor_expired400The snapshot of the cursor expired.
unknown_operator, no_update, conflicting_update, invalid_field, unindexed_many, empty_filter400An update or delete breaks the contract.
invalid_pattern400A collection pattern that is not a prefix and one * at the end.
pattern_read_only400A write or admin route on a collection pattern.
pattern_too_wide400The pattern matches more than 256 collections.
out_of_window400A restore to an instant out of the PITR window; the message gives the start of the window.
pitr_off400A restore of a collection with pitr: off.
lookup_invalid400A lookup or $lookup that is not valid (a relation without a kind or a foreign key, an unknown key, more than two levels, a $lookup before another stage).
lookup_unindexed400The other side of a lookup has no index on the field it searches. The message gives the _indexes route.
confirm_required400_truncate or drop without confirm equal to the collection name.
catalog_invalid400The collection definition or name is not valid (for example, it has id).
ttl_not_enabled400expire_in, _expire or _persist on a collection without expires_field.
ttl_derived400The same on a collection whose expiry comes from ttl + time.
not_supported400The route does not exist for a direct-mode collection.
invalid_doc, missing_id, invalid_id, immutable_id, invalid_batch, invalid_path, invalid_index400A document or a definition is not valid.
invalid_blob_ref400The blob reference is not sha256:<64 hex>.
invalid_position400The watch position is not valid.
not_a_stream400A stream route, or "stream": true, on a collection that is not a stream.
stream_append_only400A write route of every collection (_doc POST, _bulk, _update, _update_by_query, _delete_by_query, _expire, _persist) on a stream.
invalid_stream_id, stream_id_too_small400A stream entry ID that is not <ms>-<seq> (or 0-0 in an append), or an append ID that is not greater than the last one.
unknown_group404The stream group does not exist.
group_exists409A stream group create with a name that exists.
unauthorized401A TCP request without a known bearer token (-token-file or tokens:).
forbidden403A scoped token without the right for this route and collection; POST /_backup or POST /_cluster/key over TCP; a browser request from an origin not in cors_origins; a TCP request with no token and a Host not allowed (see Security).
too_many_requests429The client IP failed the token check too many times (auth_failures), or max_watches streams are open. Wait for Retry-After seconds.
not_found404No document (or blob) with this id.
locked423Another caller holds the lock of the document: a _lock whose wait is over, or a many write that meets a locked document.
key_rotating409A key rotation while another one is not finished. See GET /_cluster/settings.
tx_conflict409An update or a delete of a transaction matched nothing: no such document, or its query (a _v guard) does not match. Nothing of the transaction was written; the message names the op.
lock_expired409A write or an _unlock with a lock token that holds no lock on the document: the lock expired or was released. Nothing was written.
unknown_collection404The collection does not exist.
collection_exists409A rename to a name that exists (without replace), or a restore to a name that exists.
unknown_route404No route has this path.
method_not_allowed405The path exists with other methods (see Allow).
invalid_range416The Range of a GET /_blobs/{ref} is out of the blob. Content-Range: bytes */<size> gives the size.
duplicate_id409A document with this _id exists.
unique_violation409A unique field value exists.
catalog_conflict409Two declarations disagree (write, path, time).
direct_collection409A write on a direct-mode collection.
history_truncated410A _watch needs WAL files that wal_retention deleted.
request_too_large, line_too_large413The body or a line is over max_line_size (or the blob limit).
lookup_too_large422A lookup attaches more than 10 000 documents to one answer.
group_limit_exceeded422The group table of an aggregate is over its memory limit.
canceled499The client left before the answer (logs and metrics only).
internal500A bug or a disk error. The message stays in the daemon log.
not_ready503The daemon is recovering. Retry.
closed, stopping503The daemon is shutting down. Retry on another daemon or later.
watch_lagged(stream)The consumer was too slow. Reconnect: it resumes after the last ack.