> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Setting up Context.dev for a user? Follow https://docs.context.dev/agent-quickstart.md. MCP clients sign in with OAuth and need no API key; application code reads CONTEXT_DEV_API_KEY.

# Cancel, limits, and errors

> Cancel or delete a batch, stay within batch concurrency and rate limits, and handle each error the Batches API returns.

## Cancel a batch

`POST /v1/batch/{batch_id}/cancel` stops a batch from starting new pages. It returns `202` with `status: "cancelling"`. Pages already in progress finish, then the batch becomes `cancelled`. Pages that never started stay in `progress.pending` and get no result records.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import ContextDev from "context.dev";

  const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });

  const batch = await client.batch.cancel("batch_9f2c8a");
  console.log(batch.status);
  ```

  ```python Python theme={null}
  import os
  from context.dev import ContextDev

  client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

  batch = client.batch.cancel("batch_9f2c8a")
  print(batch.status)
  ```

  ```ruby Ruby theme={null}
  require "cgi/core"
  require "context_dev"

  client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

  batch = client.batch.cancel("batch_9f2c8a")
  puts batch.status
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	contextdev "github.com/context-dot-dev/context-go-sdk/v2"
  	"github.com/context-dot-dev/context-go-sdk/v2/option"
  )

  func main() {
  	client := contextdev.NewClient(option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")))

  	batch, err := client.Batch.Cancel(context.Background(), "batch_9f2c8a")
  	if err != nil {
  		panic(err)
  	}
  	fmt.Println(batch.Status)
  }
  ```

  ```php PHP theme={null}
  <?php
  require __DIR__.'/vendor/autoload.php';

  use ContextDev\Client;

  $client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

  $batch = $client->batch->cancel("batch_9f2c8a");
  echo $batch->status, PHP_EOL;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.context.dev/v1/batch/batch_9f2c8a/cancel \
    -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"
  ```
</CodeGroup>

```json theme={null}
{
  "id": "batch_9f2c8a",
  "status": "cancelling",
  "progress": { "succeeded": 740, "failed": 3, "pending": 1257 }
}
```

Retrieve the batch for its final state and results once it's `cancelled`. Cancelling a batch that's already final returns `409 BATCH_NOT_CANCELLABLE`.

## Delete a batch

`DELETE /v1/batch/{batch_id}` permanently deletes a finished batch and its result files, and returns `{"id": "batch_9f2c8a", "deleted": true}`.

* While the batch is active, and briefly after it finishes while its usage settles, delete returns `409 BATCH_NOT_COMPLETED`. Cancel it if needed, wait for a final status, and retry.
* Its webhook delivery can no longer be retried or replayed.
* Its `Idempotency-Key` can be used for a new batch.

## Limits

| Limit | Value |
| - | - |
| URLs per batch | 1 to 25,000 |
| Request body | 8 MB |
| Active batches (`queued`, `running`, or `cancelling`) | Free 1, Developer 2, Pro 5, Growth 5, Scale 20 |
| Batches API rate limit | 1,000 units per minute per organization. A submit uses 50 units; every other batch call uses 1. |

Above the active-batch limit, submit returns `403 BATCH_LIMIT_EXCEEDED`. Wait for a batch to finish, or cancel one. Your organization may have a custom limit. See [Rate limits](/optimization/rate-limits) for how rate limits apply across the API.

Submit also needs enough credits to cover every page the batch accepts, or up to `maxUrls` pages for a crawl. When it can't, it returns `401 USAGE_EXCEEDED` and no batch is created. See [credits](/account/credits).

## Errors

| Status | `error_code` | Cause | What to do |
| - | - | - | - |
| 400 | `INPUT_VALIDATION_ERROR` | Invalid body, unknown key, no usable URLs, more than 25,000 URLs, `webhook` sent with `webhookUrl`, or a bad `cursor`. | Fix the request. |
| 401 | `USAGE_EXCEEDED` | Not enough credits for the batch. | Add credits, or submit fewer URLs. |
| 401 | | Missing, invalid, or disabled API key. | Check the key. |
| 403 | `BATCH_LIMIT_EXCEEDED` | Too many active batches. | Wait for one to finish, or cancel one. |
| 403 | `INSUFFICIENT_PERMISSIONS` | A restricted key lacks `batches:read` or `batches:write`. | Use a key with that scope. |
| 404 | `NOT_FOUND` | No batch with that ID in your organization. | Check the ID. |
| 409 | `IDEMPOTENCY_KEY_CONFLICT` | The key was used with a different body, or the first request with this key is still in progress. | Send the original body, or retry in a moment. |
| 409 | `BATCH_NOT_COMPLETED` | Results or delete requested before the batch is final or settled. | Wait for a final status, then retry. |
| 409 | `BATCH_NOT_CANCELLABLE` | Cancel requested for a batch that's already final. | Nothing to cancel. |
| 429 | `RATE_LIMITED` | Batches API rate limit exceeded. | Back off and retry. |
| 500 | `INTERNAL_ERROR` | The batch couldn't be staged or queued. | See below. |
| 503 | `SEARCH_UNAVAILABLE` | Batch list search with `q` or `tags` is unavailable. | Retry, or list without `q` and `tags`. |

A `500` from submit can mean two things. If the batch was never created, retrying with the same `Idempotency-Key` is safe. If it was created but its work couldn't be queued, the same key returns that batch with `status: "failed"` and `failure.code: "enqueue_failed"`, so submit again with a new key.

Failures of individual pages don't produce HTTP errors. They appear as result records with `status: "error"`; see [page error codes](/batches/results#read-results).

## Related

* [Status and results](/batches/results): progress, results, and retention.
* [Submit a batch](/batches/submit): idempotency and submission rules.
* [Cancel a batch reference](/api-reference/batches/cancel) and [Delete a batch reference](/api-reference/batches/delete)