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.
`invalid_arguments`	A handoff create, prepare, complete, or asset request is malformed or no longer valid. Handoff-specific payloads usually include `originalCode: "AgentAskHandoffError"`.	Inspect `message` and, when available, the handoff status `nextAction`.
`max_payment_exceeded`	The quoted or prepared ask costs more than the caller's saved payment cap.	Copy `maxPaymentAmountHint` from a fresh quote or ask the user to approve a higher cap.
`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
}

Browser Handoff Image Cap

Browser handoff images accept JPG, PNG, and WEBP inputs up to 10 MB per image.

{
  "code": "invalid_arguments",
  "originalCode": "AgentAskHandoffError",
  "message": "generatedImages[0] exceeds the maximum image upload size of 10485760 bytes.",
  "recoverWith": "fix_tool_arguments",
  "retryable": false,
  "status": 400
}

Expired Handoff Link

Expired handoffs cannot be prepared again. If the link expired before funding, create a new link; if it expired after wallet transactions were submitted, use the recovery guidance in the completion error.

{
  "code": "invalid_arguments",
  "originalCode": "AgentAskHandoffError",
  "message": "Handoff link has expired. Ask the AI agent to generate a new handoff link.",
  "recoverWith": "fix_tool_arguments",
  "retryable": false,
  "status": 410
}

Interrupted Image Staging

File-backed handoffs can return a non-terminal staging status before bytes arrive or moderation finishes. Poll status first; if the image fails or stays interrupted, retry or remove the asset from the handoff page, or ask for a fresh link with the image reattached.

{
  "status": "uploading_images",
  "nextAction": "Image upload is still processing. Poll rateloop_get_handoff_status for completion or failure."
}

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.