---
title: "Explain a platform error"
method: POST
path: "/api/v1/tools/explain_error/execute"
tags: ["Adako"]
---

# Explain a platform error

`POST /api/v1/tools/explain_error/execute`

## Request

- Base URL: `https://adako.ai`
- URL: `https://adako.ai/api/v1/tools/explain_error/execute`
- Auth: HTTP bearer

Translates a raw error from any connected ad platform into a plain-language cause, a concrete fix, and the Adako tool to call next. Deterministic rule table, no guessing.
Covers Google Ads error codes, Meta Graph codes, ChatGPT Ads HTTP shapes, TikTok numeric codes and LinkedIn codes.
Use when: a tool returned platform_error, or the user pastes an error from the platform UI.
When not to use: the failure was an Adako error (quota, validation, not connected) — call why_did_this_fail instead, which reads the real call log.
Returns the best-matching rule with cause, fix and next tool. If nothing matches it says so and lists what it does know for that platform; never invent a cause.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `arguments` object, required
    - `error_text` string, required: The raw error message or JSON, pasted verbatim.
    - `platform` 'google_ads' | 'meta_ads' | 'chatgpt_ads' | 'tiktok_ads' | 'linkedin_ads': Narrows the rule table. Pass it whenever you know the platform: HTTP statuses like 401 mean different things on different platforms.

## Response `200`

The tool ran. A write returns proposal_id and approve_url while the change waits for approval.

- SuccessEnvelope
  - `success` unknown, required
  - `tool` string, required
  - `data` object, required: Machine-readable result.
  - `markdown` string, required: The same result written for a person or a model.
  - `quota` Quota: Task usage for the current billing period.
    - `plan` string
    - `used` integer
    - `limit` integer
    - `period_end` string
    - `upgrade_url` string
  - `proposal_id` string: Present for writes. Nothing changes on the ad platform until it is approved.
  - `approve_url` string: Where a person approves the proposal.
  - `request_id` string, required

## Other responses

- `400`: Invalid arguments, or the ad account could not be resolved.
- `401`: Missing, invalid, revoked or expired API key.
- `402`: Monthly task quota used up, or the plan does not include this tool.
- `403`: The connected ad account lacks the access level this tool needs.
- `404`: Unknown tool name.
- `409`: Not connected, reconnect needed, confirmation required, a proposal already pending or no longer pending, an identical create that failed earlier today (proposal_failed_before), a create that duplicates an approved one (duplicate_create), the ad-account limit of the plan reached (account_limit), or an Idempotency-Key reused with different arguments.
- `429`: Rate limited by Adako or by the ad platform. See Retry-After.
- `500`: Unexpected error inside Adako.
- `502`: The ad platform returned an error.

---

[API](https://skmtc.dev/adako/apis/adako-rest-api.md) · [All operations](https://skmtc.dev/adako/apis/adako-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adako/apis/adako-rest-api/revisions/59ee60d48a56?raw)