Errors and retry decisions

AIP errors separate machine decisions from diagnostic text. Read the protocol code, category, retry hint, action or transaction state, and connector outcome evidence before deciding to correct, authorize, retry, reconcile, or stop.

This reference describes source revision d7cce13d1d555644d04a4d73c66c95b113737635. It covers native AIP and the product-neutral connector fleet. Product-specific error codes and recovery procedures belong to each of the six connector troubleshooting sections.

Protocol error object

ProtocolError has three required fields and four optional fields:

Optional fields are omitted when absent; the Rust serializer does not emit them as null. Automation should use code, category, and explicit retry state. It must not match on message text.

{
  "code": "idempotency.in_progress",
  "message": "another execution owns this idempotency key",
  "category": "temporary",
  "retryable": true,
  "retry_after_ms": 1250,
  "details": {
    "key": "booking-create-0190",
    "owner_action_id": "act_0190c42f2d5a70008000000000000001",
    "reservation_expires_at": "2026-07-26T12:00:01.25Z"
  },
  "source": {
    "component": "aip-runtime"
  }
}

The protocol type permits arbitrary JSON in details and source. The typed connector boundary requires redacted details, but consumers must not assume that every producer enforced redaction. Apply authorization and logging policy before returning, retaining, or exporting either field.

Categories and native HTTP mapping

The native HTTP binding maps a protocol category to a recommended status:

This mapping applies when an HTTP handler delegates status selection to the native binding. A route may intentionally use a more specific status. For example, connector-host capacity returns 429 and replay returns 409. Always parse the response body as well as the status.

Where an error appears

Native error envelope

A message-level failure is carried in an envelope with message type aip.core.v1.error and body.error.error containing ProtocolError. Native HTTP returns that envelope with a mapped status. Native NATS returns the same error envelope without an HTTP status.

The signed connector-host path correlates an error response to the request, addresses it to the request sender, and signs it. A client must verify the response signature and correlation before trusting the embedded error.

Failed action result

A capability may return an ActionResult whose status is failed and whose error is a ProtocolError. The enclosing HTTP request can still succeed. Inspect the action result instead of treating HTTP success as action success.

An acknowledgement can also reject or queue an action and carry reason and retry_after_ms without a ProtocolError. Treat those as acknowledgement state, not as a substitute error object.

Compact HTTP error

Some pre-envelope or ergonomic routes return a compact object under error. Examples include JSON decoding before an envelope exists and capability-catalog discovery. A compact error can omit category, retry fields, or source. Use the route’s documented status and code; do not synthesize missing retry authority.

Model Context Protocol mapping

The Model Context Protocol (MCP) profile maps AIP categories to JSON-RPC codes:

When an AIP error has details, the current mapper uses those details directly as JSON-RPC data. When details are absent, data contains AIP extension metadata with code, category, retry fields, and source. A generic MCP client must therefore not assume that every projected failure exposes the AIP code.

Retry decision order

Apply these checks in order. A later yes cannot override an earlier stop.

At this revision, queued-runtime retry policy behaves as follows:

• safe and safe_with_idempotency_key capabilities receive a maximum of three attempts by default; unsafe and unknown receive one;
• safe_with_idempotency_key cannot retry without an idempotency key;
• retryable: false always stops the runtime retry;
• retryable: true permits the error-hint gate, subject to every other gate;
• absent retryable falls back to configured categories, whose default set is temporary, transport, and connector;
• retry_after_ms is clamped to at least 1 ms and at most the policy’s maximum backoff; absent delay uses bounded exponential backoff;
• the retry is rejected if the next delay exceeds max_elapsed_ms.

These are current runtime defaults, not a protocol mandate for every AIP implementation. A client should read durable status before resubmitting after an interrupted transport exchange.

Unknown outcomes

A transport failure after dispatch does not prove that a provider mutation did not happen. A typed ConnectorFailure carries the evidence needed to choose a safe branch:

The conversion to ProtocolError places these values in details and preserves the connector’s code, category, retry flag, and delay. Conversion in the other direction treats absent retryable as false.

For transaction modes commit and execute, the runtime moves the transaction toward outcome_unknown when the result has code sla.timeout_exceeded or details.uncertain_outcome is true. Use the captured provider operation ID and the reconciliation action. Do not create a second mutation merely because a transport or timeout category looks temporary.

Common native code families

The table lists product-neutral families implemented at the pinned revision. It is a lookup aid, not an exhaustive registry of provider-specific codes.

Connector-fleet runtime errors

Catalog and central admission

The tenant capability-catalog route uses compact HTTP errors:

Central remote routing and admission return structured protocol errors where the condition has a stable client decision:

Binding absence, replica unavailability, stale registry state, fence loss, and storage failures can surface through a broader runtime error when no dedicated protocol mapping exists. Operators should inspect registry and fleet state rather than infer a specific code from generic handler text.

Connector-host execution

Authenticated host requests receive a signed error envelope for these conditions:

Schema/decode failures and response-signing failures occur before a trustworthy signed response can be produced. Those paths use compact unsigned JSON with 400 or 500. Treat an unsigned failure as transport evidence only; never accept its body as authenticated host state.

Event and stream-callback ingress

Registry and admission operator failures

Registry and admission CLI commands fail through standard error and non-zero exit status. Their Rust error families are not ProtocolError codes and do not carry a wire-level retry flag.

Use connector registry plan to verify without writing. apply journals and resumes an exact package revision and digest; status is the recovery source. Do not repeatedly invoke apply based only on an error string.

Callback and delivery failures

Action execution, callback delivery, and event ingestion are separate durable boundaries. A completed action can coexist with a failed callback. Recover the callback from its durable outbox or event state; do not rerun the provider action to compensate for delivery failure.

Likewise, a successful transport response can contain a failed action result, and a failed transport exchange can leave an action running. Read action, transaction, event, and receipt state before choosing another mutation.

Security and observability

• Log code, category, action ID, transaction ID, correlation ID, retry decision, attempt, and redacted source metadata.
• Do not log credentials, raw provider bodies, bearer tokens, signing seeds, or unreviewed details.
• Keep one metric label set per bounded code family; do not label by free-form message, tenant, provider request ID, or resource ID.
• Treat signature, tenant, route, credential-revision, approval-conflict, replay, and fence failures as security events, not ordinary availability.
• Preserve durable receipts and provider operation references for an unknown outcome or contested retry.

Related reference

• Native HTTP API
• Connector fleet HTTP API
• Transport bindings
• getaip CLI
• Actions and sessions