# Errors and idempotency

## Errors and idempotency

Agent systems need failure behavior that is predictable enough to automate against. Aeeron treats payment failures and execution failures as different states because they represent different operational realities. A failure before the provider is touched usually calls for a replay or a policy decision. A failure after payment has cleared may require reconciliation, provider escalation, or refund logic. If those cases are collapsed into one generic error, the client loses the ability to respond safely.

### Common error codes

#### `payment_required`

This error means the action is valid but the required funding has not yet been attached. It should be handled as a normal branch in the control flow, not as an unexpected exception.

#### `budget_exceeded`

This error means the quoted or requested action exceeds the budget policy supplied by the caller. It is usually a signal to reject, escalate, or re-plan rather than to retry blindly.

#### `invalid_input`

This error means the request failed schema or semantic validation. In well-structured clients, these errors should be rare because the action definition and local validation logic should catch them before the request is sent.

#### `provider_unavailable`

This error means the downstream provider is temporarily unable to accept or complete the requested work. Recovery behavior depends on whether payment has already cleared and whether the provider operation was ever started.

#### `execution_failed`

This error means the action reached the provider layer but did not complete successfully. At this point the right response is usually reconciliation and operator review rather than simple replay, because the provider may have partially processed the request.

### Example error payload

```json
{
  "error": {
    "code": "budget_exceeded",
    "message": "Quoted amount is higher than the allowed budget.",
    "details": {
      "budget": "12.00",
      "quote": "16.80",
      "currency": "USDC"
    }
  }
}
```

### Idempotency rules

Idempotency should be treated as part of the economic safety model, not just as a transport convenience. One idempotency key should map to one business intent. If the network fails, the exact same request should be retried with the same key so the server can collapse the replay into the original operation. If the agent changes the input or reconsiders the intent, it should generate a new key. Reusing a key across different payloads makes state ambiguous and undermines replay safety.

### Safe retry pattern

The safe retry pattern is straightforward but non-negotiable. Persist the payload locally, generate the idempotency key before the first request, and keep both together in storage. If the network fails, retry with the same key. If the provider fails after execution has begun, inspect the execution resource before attempting any replay. The main mistake to avoid is firing a second economically meaningful request before the first one has been conclusively classified.

### Why this matters

Without idempotency and explicit failure state, an agent can double-pay, double-provision infrastructure, or purchase the same external service twice. Those outcomes are unacceptable in any production environment. Aeeron keeps replay behavior explicit so the client can remain aggressive about reliability without becoming dangerous about money.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aeeron.gitbook.io/aeeron-docs/errors-and-idempotency.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.