why_did_this_fail

Diagnostic & Helper Read

Summarize the user's recent failed tool calls and the errors, so you can correct and retry

Endpoint

POST https://api.adspirer.ai/api/v1/tools/why_did_this_fail/execute

Headers

Authorization: Bearer sk_live_... — your Adspirer API key (required)
Content-Type: application/json (required)
Idempotency-Key: <uuid> — recommended for write operations to make retries safe

Description

Summarize the user's recent failed tool calls and the errors, so you can correct and retry. Use after something 'didn't work' or 'failed'.

Request body

All tool arguments are wrapped in an arguments object.

Field	Type	Description
`platform`	`string` optional	Optional platform filter. one of: `google_ads`, `meta_ads`, `tiktok_ads`, `linkedin_ads`
`limit`	`integer` optional	How many recent failures to list (default 5).

Example request

{
  "arguments": {
    "platform": "google_ads"
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for why_did_this_fail)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "why_did_this_fail"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "why_did_this_fail"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "why_did_this_fail",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Diagnostic & Helper · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai