Service limits and errors

Find content and retrieval limits, proposal retention, error types, and retry guidance.

Check these limits when preparing content or handling request failures. Confirm deployment overrides with your administrator.

The API reference defines field formats and operation-specific schemas.

Content limits

These defaults can be lower in your deployment. Byte limits apply to decoded content, not base64 length. A kibibyte (KiB) is 1,024 bytes; a mebibyte (MiB) is 1,024 KiB.

Retained data includes version content and resources. Withdrawal does not free capacity; deletion removes the entry's history. You cannot delete an individual version.

These field and structure limits also apply:

Retrieval limits

Pins consume discovery slots and preview budget. The preview ceiling applies to discovery rather than type-specific search, loaded instructions, or fetched files. See Retrieve knowledge for the behavior of each setting.

Follow a list response's next cursor until it is absent, even if a page is empty. Keep the collection, filters, and ordering consistent between pages. Lists reflect concurrent changes and do not represent a fixed snapshot.

List responses return items and nextCursor and do not include a total count. Use the cursor, not the page length, to decide when to stop. For separate observed counts, use get_playbook_stats; an unavailable count is not zero. See List entries and inspect history for examples.

Proposal and evidence limits

The optional creation source is separate from attached evidence and does not increment evidenceCount. Unreviewed proposals leave the inbox at inboxExpiresAt and become unavailable after purgeAt. With the default policy, creation, new evidence, candidate replacement, and restoration set deadlines of 30 days for inbox review and 60 days for retention. Dismissing a proposal moves it to trash immediately and starts a 30-day retention window. An exact evidence retry does not refresh the deadlines.

Proposal retention does not affect an accepted entry's history. Store required review records outside the inbox.

Handle request errors

HTTP errors include a status and machine-readable type. Use the type to choose a recovery action. For MCP, inspect isError before reading tool content. See MCP troubleshooting.

For example, inspect a failed entry read without retrying it automatically. Use the client setup and export the FAQ identifier you want to inspect:

export PLAYBOOK_FAQ_ID='<faq-entry-id>'

import json
import os
from redis_agent_playbook.errors import PlaybookError

try:
    entry = playbook.client.get_faq(faq_id=os.environ["PLAYBOOK_FAQ_ID"])
    print(entry)
except PlaybookError as error:
    try:
        problem = json.loads(error.body)
    except ValueError:
        problem = {}
    print("Request failed:", error.status_code, problem.get("type", "unknown"))
    raise

STATUS=$(curl --silent --show-error -o response.json -w '%{http_code}' \
  "$PLAYBOOK_API/faqs/$PLAYBOOK_FAQ_ID" \
  -H "Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_API_KEY")
if [[ "$STATUS" == 2* ]]; then
  jq . response.json
else
  printf 'Request failed: HTTP %s\n' "$STATUS" >&2
  jq -r '.type // "unknown"' response.json >&2 2>/dev/null || printf 'unknown\n' >&2
  exit 1
fi

Resolve conflicts

The 409 error type identifies the recovery step:

Retry uncertain operations

Use bounded retries for reads and transient failures. Proposal acceptance can resume its recorded target. For an exact evidence retry, keep the same identifier and payload.

A timeout, including 408, does not prove a create or append failed. Read state before retrying to avoid another entry or version. Check the Python SDK retry configuration when controlling write retries.

Bulk deletion is not atomic across the batch. The response lists removed entries in deleted and entries it couldn't delete in errors. Earlier deletions remain applied after a later failure. Retrying the same batch is safe because absent entries are ignored.

Remove content in bulk

Use a key with write permission for bulk deletion. Choose the entry type before sending a request:

Bulk deletion accepts 1–100 entry identifiers of the selected type. The data plane does not provide an operation to clear an entire playbook. An administrator can clear content through the control plane or the console's Danger zone.

For ordinary sample cleanup, use the single-entry deletion steps in Manage FAQs or Manage skills.