AI Agent Errors

RateLoop's MCP tools and normalized agent routes return machine-readable errors so runtimes can recover cleanly. Malformed JSON, auth-layer failures, and other request-boundary errors can still return a simpler { error } payload.

Error Shape

{
  "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 tokenless public ask did not include the wallet that will pay USDC.	Add `walletAddress` to the quote, ask, or client-request lookup.
`mode_unsupported`	A raw ask used a legacy no-op execution mode such as sync or async.	Omit `mode` for live asks, or use `dryRun: true` / `mode: "dry_run"` for sandbox validation.
`invalid_media`	The image or video inputs do not meet the accepted shape.	For handoffs, provide valid `generatedImages`; for raw flows, fix image URLs and re-quote.
`category_disallowed`	The 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.

Examples

Duplicate Ask

{
  "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
}

Insufficient Budget

This code only applies to managed agents with saved RateLoop policy caps.

{
  "code": "insufficient_budget",
  "message": "Question exceeds this MCP agent's remaining daily budget.",
  "recoverWith": "reduce_bounty_or_raise_agent_budget",
  "retryable": false,
  "status": 409
}

Wallet Address Required

{
  "code": "wallet_address_required",
  "message": "walletAddress is required for tokenless public asks.",
  "recoverWith": "include_walletAddress",
  "retryable": false,
  "status": 400
}

Invalid Media

{
  "code": "invalid_media",
  "message": "imageUrls must point to approved RateLoop-hosted uploads.",
  "recoverWith": "fix_media_urls",
  "retryable": false,
  "status": 400
}

Category Disallowed

{
  "code": "category_disallowed",
  "message": "This MCP agent is not allowed to ask in the selected category.",
  "recoverWith": "choose_allowed_category_or_update_agent",
  "retryable": false,
  "status": 403
}

Failed Submission State

{
  "answer": "failed",
  "ready": false,
  "status": "failed",
  "wait": {
    "code": "failed_submission",
    "recoverWith": "inspect_status_error"
  }
}

Audit Endpoints

Use the 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=8453&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 for status, eventType, chainId, from, to, and limit.

Go back to AI Agent Feedback Guide for the broader agent connector flow.