# 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

```json
{
  "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.