DocumentationErrors and challenges

Errors and challenges

What an action can end with, and what to do next.

Action statuses

queued: Waiting to start.
running: Running in the account's browser.
needs_input: A challenge waits for an answer. See challenge.
succeeded: Done. See result.
failed: Stopped. See error.
canceled: Canceled before it finished.

Error object

A failed action still answers 200 or 202. Read status and error.

Action (trimmed)

{
  "status": "failed",
  "error": { "code": "rate_limited", "message": "..." }
}

Error codes

Code	Meaning	Do
`signed_out`	The account is signed out and no stored credentials could sign it in again.	Connect again, or send the owner a sign-in link.
`login_failed`	The platform refused the username, password or code.	Fix `credentials` with `PATCH /v1/accounts/{id}`, then connect again.
`account_blocked`	The platform shows a checkpoint or a suspension on the account.	Open a sign-in link and clear the checkpoint in the live browser.
`rate_limited`	The platform asked the account to slow down. Try again later.	Space out actions on this account.
`not_found`	The post, person or conversation does not exist or is not visible to the account.	Check the URL, handle or id.
`unsupported`	This platform has no such action.	Use `browser` steps, or send feedback.
`invalid_input`	A parameter is missing or has the wrong shape.	Check the parameters in the action reference.
`rejected`	The platform refused the action, for example a duplicate post.	Read `message`, change the request, retry.
`ui_changed`	The page did not look the way the driver expects. We are told and fix it.	Retry later.
`challenge_timeout`	A sign-in challenge was not answered before it expired.	Run the action again and answer in time.
`browser_unavailable`	No browser could be started. Nothing was charged; try again.	Retry with the same `Idempotency-Key`.
`browser_error`	The browser failed while running the action.	Retry. If it repeats, send feedback.
`insufficient_credits`	The balance is too low for this action. Top up and try again.	Top up with x402 or in the web app.

Challenges

A sign-in step BuzzTake cannot finish alone stops the action at needs_input. Answer before expires_at, or the action fails with challenge_timeout.

Action (trimmed)

{
  "status": "needs_input",
  "challenge": {
    "kind": "two_factor_code",
    "message": "Enter the code from your authenticator app.",
    "expires_at": "2026-10-14T09:10:00Z",
    "sign_in_url": "https://buzztake.com/connect/bts_..."
  }
}

Kind	Meaning	Answer with
`two_factor_code`	A code from an authenticator app.	API or MCP. With a stored `totp_secret`, BuzzTake answers it itself.
`email_code`	A code the platform sent by email.	API or MCP.
`sms_code`	A code the platform sent by text message.	API or MCP.
`device_approval`	Approve the sign-in on another device.	Approve on the other device, or use the live browser.
`captcha`	A puzzle the platform shows to a new sign-in.	Live browser.
`other`	Anything else the page asks for. The message says what.	Read `message`. API, MCP or live browser.

Three ways to answer

API	`POST /v1/actions/{id}/answer` with `{ "answer": "..." }`.
MCP	The tool result carries the challenge. Pass the answer back through the server.
Live browser	Open `sign_in_url`. It works for 30 minutes, without a BuzzTake login.

POST/v1/actions/{id}/answer

Request

curl -X POST https://api.buzztake.com/v1/actions/$ACTION_ID/answer \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "answer": "123456" }'

Request errors

A request that fails creates no action and costs nothing.

HTTP	Meaning
400	The request is malformed, such as bad JSON.
401	The API key is missing or not valid.
403	The key may not act on this workspace or account.
404	No such account, action or workspace for this key.
409	The request conflicts with the current state.
422	A field has the wrong value or shape.
429	Too many requests. Wait, then retry. Honour `Retry-After` when present.