Errors and limits

Handling GraphQL errors

Inspect errors[].extensions to handle failures. Do not parse human-readable message text; wording is not a machine-readable contract.

{
  "data": null,
  "errors": [
    {
      "message": "first must be between 1 and 500.",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "reason": "PAGINATION_CONSTRAINT",
        "field": "first",
        "constraint": "range"
      }
    }
  ]
}

Limits

Input	Contract
Key	^[\\w-]+(:[\\w-]+)*$
itemId	Same pattern; maximum 256 characters
JSON value	Maximum 10,240 bytes
first	1–500; omitted or null defaults to 20
ids plus itemIds	Maximum 100 raw selectors
Service-generated ID selector	Exactly 24 hexadecimal characters
Replacement items	Non-empty
Replacement identities	Unique within the request

The selector limit applies before deduplication. null selector lists are treated as empty.

Error reference

Reason or code	Applies to	Useful extensions
IDENTIFIER_CONSTRAINT	Key or itemId	identifierType, constraint
EMPTY_SELECTOR	Lookup and delete	—
SELECTOR_LIMIT_EXCEEDED	Lookup and delete	—
INVALID_DOCUMENT_ID	Lookup and delete	field, value
PAGINATION_CONSTRAINT	List and lookup	field: first, constraint: range
CURSOR_CONSTRAINT	List and lookup	field: after, cursor constraint
DATETIME_CONSTRAINT	sortDate	Datetime constraint
EMPTY_ARRAY	Whole-array replacement	—
DUPLICATE_ITEM_ID	replaceArrayItems	itemId
CONCURRENT_WRITE_CONFLICT	Array mutations	Code
JSON validation error	JSON inputs	Do not rely on message text

Cursor constraints are malformed, unsupportedVersion, and queryMismatch.

Datetime constraints are type, format, finite, integer, and range.

A concurrent-write conflict means the transaction could not be completed. Stored data remains unchanged.

A missing getArrayItem produces a GraphQL error, but there is currently no stable operation-specific extensions.reason. Do not treat its current message text as a contract.

Datetime input format

String inputs

Accepted forms include:

• YYYY-MM-DD
• YYYY-MM-DDTHH:mm:ss
• The same date-time with a one- to three-digit fraction
• An uppercase Z, +HH:mm, or -HH:mm offset

Examples:

2026-09-18
2026-09-18T10:30:00
2026-09-18T10:30:00.123Z
2026-09-18T12:30:00+02:00

Date-only and zone-less date-time values use UTC. Invalid calendar dates and invalid offsets are rejected.

Numeric inputs

Numeric values must be integral Unix epoch milliseconds, finite, and within the JavaScript Date range. Fractional values are rejected.

Output format

Datetime outputs are canonical ISO strings, for example:

2026-09-18T10:30:00.000Z

Validation order

The first applicable validation failure is returned.

listArrayItems

1. first
2. Cursor syntax and version
3. Cursor query binding

lookupArrayItems

1. Identifier coercion
2. Empty selectors
3. Raw selector limit
4. Service-generated ID validation
5. Page size
6. Cursor validation

deleteArrayItems

1. Identifier coercion
2. Empty selectors
3. Raw selector limit
4. Service-generated ID validation

replaceArrayItems

1. Identifier coercion
2. Empty items
3. Duplicate itemId values