# Error Recovery Patterns

## The validate → repair → retry loop

```
LLM produces raw tool call
    ↓
Parse JSON (syntax check)
    ↓  fail → send error back to LLM
jsonschema.validate (semantic check)
    ↓  fail → repair attempt (strip unknown keys, fill defaults)
    ↓  still fail → send error back to LLM
Execute tool
    ↓  fail → structured error envelope
Return result to LLM
```

## Structured error envelope

```json
{
  "error": "City 'Xyzzy' not found in weather database",
  "code": "CITY_NOT_FOUND",
  "retryable": false,
  "suggestion": "Try a major city name like 'London' or 'Tokyo'"
}
```

Key fields:
- `code`: machine-readable, for agent decision logic
- `retryable`: `true` = agent should retry with corrected args; `false` = ask user
- `suggestion`: helps the LLM produce a better next call

## Retry cap configuration

```python
MAX_TOOL_RETRIES = 3            # Per individual tool call
MAX_TOOL_CALLS_PER_TURN = 10    # Total tool calls in one agent turn
RETRY_TIMEOUT_SECONDS = 30      # Hard wall-clock cap
```

## Common validation failures

| Failure | Cause | Repair |
|---------|-------|--------|
| Missing required field | LLM omitted it | Prompt LLM with "field X is required" |
| Unknown parameter | LLM hallucinated a field | Drop it silently |
| Type mismatch | `"8080"` vs `8080` | Coerce if safe, else reject |
| Enum violation | `"kelvin"` not in `["celsius","fahrenheit"]` | Prompt LLM with valid options |
| Out of range | `temperature: 9999` | Reject, send valid range |