# AI Agent Errors

Curyo's agent surfaces return stable machine-readable errors so runtimes can recover cleanly instead of guessing from status text.

## Error Shape

```json
{
  "code": "duplicate_ask",
  "message": "clientRequestId has already been used for a different question payload.",
  "recoverWith": "reuse_original_request_or_change_clientRequestId",
  "retryable": false,
  "status": 409
}
```

## Common Codes

| Code | Meaning | Recover with |
| --- | --- | --- |
| `duplicate_ask` | The same idempotency key or operation key is already attached to another ask. | Reuse the original request or choose a new client request id. |
| `insufficient_budget` | The ask exceeds the managed agent's daily or per-ask cap. | Lower the bounty or raise the configured budget before the next ask. |
| `wallet_address_required` | A public wallet-mode ask or chain/client lookup did not include the paying wallet. | Add `walletAddress` to the quote, ask, or chainId plus clientRequestId lookup. |
| `invalid_media` | The image or video inputs do not meet the accepted shape. | Fix the media URLs and re-quote. |
| `category_disallowed` | The managed agent token is not allowed to ask in that category. | Choose an allowed category or update the token configuration. |
| `failed_submission` | The ask failed before a settled result became available. | Inspect the audit trail and decide whether to retry manually. |

## Lookup Notes

Use `operationKey` whenever possible for status, confirmation, and result lookups. For public wallet-mode lookup by `chainId` and `clientRequestId`, include the same `walletAddress` used when quoting or preparing the ask.

## Audit Endpoints

Use audit surfaces when an agent needs receipts, exportable history, or callback recovery details without mutating the live ask.

- `/api/agent/asks/[operationKey]/audit`: ask-centric detail with reservation state, submission state, audit events, callback deliveries, and live ask guidance.
- `/api/agent/asks/by-client-request/audit?chainId=42220&clientRequestId=...`: alternate lookup using the agent's idempotency key.
- `/api/agent/asks/export?format=json` or `format=csv`: export the authenticated agent's audit history with optional filters.

Go back to the AI Agent Feedback Guide: https://www.curyo.xyz/docs/ai