coordination · beta · free

Negative Cache Ticket

Prevent agent swarms from repeatedly attempting the same known-failing work. Record accepts a stable machine code only; check reveals a ticket only to callers that already know its opaque namespace and key.

Use when

Agents should share a typed, temporary record of a failed lookup.
Repeated work should pause until an explicit expiration time.

Do not use when

The failure is permanent or requires a durable incident record.
The request contains raw credentials or personal data.

Invocation contract

HTTP: /v1/tools/negative-cache-ticket
Version: 0.1.0
Mode: atomic
Idempotency: required
Retention: A derived namespaced key, stable failure code, and timestamp remain in Valkey only until expiry. Raw error messages are not accepted.
Tested with: HTTP/1.1, HTTP/2, MCP Streamable HTTP

Positive and negative examples

{
  "input": {
    "operation": "record",
    "namespace": "fetch",
    "key": "resource-42",
    "failure_code": "UPSTREAM_TIMEOUT",
    "ttl_seconds": 60
  },
  "output": {
    "ticket_hash": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
    "active": true,
    "newly_recorded": true,
    "failure_code": "UPSTREAM_TIMEOUT",
    "recorded_at": "2026-07-24T12:00:00.000Z",
    "expires_at": "2026-07-24T12:01:00.000Z",
    "ttl_seconds_remaining": 60
  },
  "negative": [
    {
      "scenario": "The failure is permanent or requires a durable incident record.",
      "expected_error": "INVALID_INPUT",
      "charged": false
    }
  ]
}

Deterministic errors

Code	Retry	Charged	Recovery
INVALID_INPUT	false	false	Correct the request to match input_schema.
TOOL_PAUSED	true	false	Wait for the operator to resume the tool.
RATE_LIMITED	true	false	Retry after the response Retry-After interval.
DEPENDENCY_UNAVAILABLE	true	false	Retry with the same idempotency identity.

Full machine manifest

The HTTP, OpenAPI, MCP, llms.txt, and ARD descriptions are generated from this same registry record.

Open JSON manifest →