> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/jobs-retries-and-errors.md).

# Jobs, retries and errors

#### Jobs

Quick tools answer straight away. Tools that take longer, such as creating a brand, drafting briefs, running the planner or making media, return a job instead:

```json
{ "job_id": "…", "kind": "draft_briefs", "status": "queued", "credits_held": 100 }
```

Follow it with `jobs_get`, every few seconds:

```bash
curl -X POST https://mcp.avastudio.com/v1/jobs_get \
  -H "x-api-key: $AVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "JOB_ID"}'
```

| `status`            | Meaning                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queued`, `running` | Still working. `progress.label` says what it is doing.                                                                                                                                       |
| `succeeded`         | Done. `result` holds the tool's output, `credits_charged` what it cost and, for media, `media_credits_charged`.                                                                              |
| `failed`            | Stopped. `error` says why. Unused holds are released; media already produced can still be charged. See [Credits and pricing](https://docs.avastudio.com/api-and-mcp/credits-and-pricing.md). |

Each tool's page in the [tool reference](https://docs.avastudio.com/api-and-mcp/tools.md) says whether it runs as a job and what its result holds. AI assistants connected over MCP follow jobs for you.

The [SDK](https://docs.avastudio.com/api-and-mcp/sdk.md#run-a-longer-task) can start and wait for a job with `ava.runJob()`, or follow a saved job id with `ava.waitForJob()`. In the [CLI](https://docs.avastudio.com/api-and-mcp/cli.md#follow-a-long-running-job), add `--wait` or use `avastudio jobs get YOUR_JOB_ID --wait`. Stopping a wait does not cancel the server's work.

Quick tools time out after 60 seconds; anything that can take longer runs as a job.

#### Retries

Networks fail. To retry safely, send an **idempotency key** with any call that changes something or costs credits, either as the `idempotency_key` input or as an `Idempotency-Key` header. Use 8 to 128 letters, digits or `_ . : -`, unique per action, for example `briefs-2026-10-08-001`.

The SDK and CLI generate a key for each paid or write call and reuse it across their automatic retries. To retry the same action in a separate call or process, retain and pass your own key: `idempotencyKey` in the SDK's call options, or `--idempotency-key` in the CLI.

For 24 hours, a call with the same key and the same input:

* runs and charges **once**;
* a retry gets the original answer, or the original job (possibly already finished: read it with `jobs_get`).

Reusing a key with **different** input is refused with `conflict`, so one key never stands for two actions.

Without a key, sending an identical job request while the first one is still queued or running also returns that same job.

#### Errors

REST errors use the HTTP status below and this body:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "draft_briefs needs a hold of 100 credits (you are charged what it uses, at most that); the balance is 42.",
    "hint": "Top up credits in Ava Studio, or request fewer briefs.",
    "request_id": "8c1f…"
  }
}
```

Over MCP, the same error comes back as a tool result marked as an error, so your assistant can read and explain it.

| Code                   | HTTP | What it means                                                                                                            | What to do                                                                                                              |
| ---------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `unauthorized`         | 401  | The key or sign-in is missing, wrong, revoked or expired.                                                                | Check the key; reconnect the app.                                                                                       |
| `forbidden`            | 403  | The key or app may not make the call, usually because it lacks the permission. The message names what is missing.        | Add the permission (create a new key).                                                                                  |
| `not_found`            | 404  | No such brand, draft, campaign or job on your account.                                                                   | Check the id.                                                                                                           |
| `invalid_input`        | 400  | The input doesn't match the tool's schema, or can't be used. `hint` says how to fix it.                                  | Fix the input.                                                                                                          |
| `insufficient_credits` | 402  | Your balance can't cover the call.                                                                                       | Top up in Ava Studio. On the Free plan, subscribe to a paid plan to get credits; over REST, the hint links it.          |
| `budget_exceeded`      | 402  | The key's or app's monthly budget can't cover the call.                                                                  | Raise the budget on the Developers page, or wait for next month.                                                        |
| `conflict`             | 409  | The idempotency key was used with different input, or the item changed meanwhile.                                        | Use a new key, or reload and retry.                                                                                     |
| `rate_limited`         | 429  | Over a limit (below). `retry_after_sec` and the `Retry-After` header say when to retry.                                  | Wait, then retry.                                                                                                       |
| `upstream_error`       | 502  | Something failed on Ava's side or at a provider. Unused holds are released; media already produced can still be charged. | Check the existing job or project before starting new work; if it keeps failing, contact support with the `request_id`. |
| `not_configured`       | 503  | The feature isn't available right now.                                                                                   | Contact support.                                                                                                        |

#### Limits

Limits depend on your plan. Calls over a limit are refused with `rate_limited` before anything is charged.

The Free limits below apply to free accounts, including accounts using [starter credits](https://docs.avastudio.com/api-and-mcp/credits-and-pricing.md#free-accounts-and-starter-credits).

|                                                                        | Free | Launch | Pro   | Growth |
| ---------------------------------------------------------------------- | ---- | ------ | ----- | ------ |
| Research calls per minute                                              | 10   | 30     | 60    | 120    |
| Research calls per day                                                 | 60   | 500    | 2,000 | 5,000  |
| Different research videos per day                                      | 60   | 500    | 2,000 | 3,000  |
| Drafting jobs at once (`draft_briefs`, `draft_clone`, `draft_iterate`) | 1    | 1      | 3     | 5      |

Every plan: other tools up to 60 calls per minute, and `draft_check` up to 500 calls per day (30 on Free). Days are UTC. Legacy Starter plans keep their earlier limits.

#### Request ids

Every response carries an `x-request-id` header, and every error names its `request_id`. You can send your own `x-request-id` (1 to 64 letters, digits, `_` or `-`) to match calls with your logs. When you contact Ava support about a call, include its request id.
