Errors and Retry Decisions

AIP errors are structured so clients can decide whether to correct input, ask for authority, wait, reconcile, or stop. Human-readable text is for diagnosis; automation should use the stable code, category, and retry fields.

Protocol Error Shape

{
  "code": "action.invalid_input",
  "message": "The required booking date is missing",
  "category": "permanent",
  "retryable": false,
  "retry_after_ms": null,
  "details": {
    "field": "date"
  },
  "source": {
    "component": "aip-connector-calendar"
  }
}

details and source must be redacted and safe for the authorized response boundary. They must never contain raw credentials.

Categories

Category	Meaning	Default HTTP status	Typical response
temporary	Service may recover without changing the request	503	Retry with bounded backoff when safe
permanent	Request or operation cannot succeed unchanged	400	Correct input or stop
auth	Authentication or authorization failed	401	Re-authenticate; do not broaden scopes automatically
policy	Authenticated request violates policy	403	Obtain approval or change the operation
economic	Billing or settlement condition failed	402	Resolve account or settlement state
connector	Downstream integration failed	502	Inspect provider status and retry safety
transport	Delivery path failed	503	Reconnect or retry only under idempotency rules

A deployment may use a more specific status where the binding defines one, but the protocol category remains stable.

Retry Rules

Retry only when all applicable conditions hold:

1. retryable is true or the capability contract independently declares the retry safe.
2. The action has the required idempotency key.
3. The downstream operation is not in outcome_unknown.
4. The retry remains inside deadline, policy, and approval validity.
5. retry_after_ms and deployment backoff limits are respected.

A temporary transport error does not prove that a provider mutation did not happen. When uncertain_outcome is true, reconcile by provider operation id.

Connector Failures

Connectors preserve provider context through stable fields:

• provider request id;
• provider operation reference;
• remote protocol status;
• retryability and retry delay;
• uncertain-outcome flag;
• failed connector operation;
• redacted details.

These fields allow recovery without exposing raw provider bodies or secrets.

Action Failure versus Delivery Failure

An action can complete while its callback fails. A callback can be retried from the durable outbox without rerunning the action. Conversely, a successful HTTP response can carry a failed action result. Always inspect the protocol body.

Validation Errors

Common native validation failures include:

• unsupported aip_version;
• message_type that does not match the body variant;
• missing or empty ids and required strings;
• null action input;
• invalid transaction selector or missing plan id;
• malformed approval evidence or constraints;
• limits outside 1-1000;
• bounded waits above 30 seconds;
• delegation chains above ten hops;
• duplicate capability ids in a manifest.

Schema validation and semantic validation are both required. Passing JSON Schema does not guarantee that cross-field protocol invariants hold.