> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Troubleshoot Agent Actions requests

Diagnose failed Agent Actions requests by status code, covering 401s, 403s, schema and API version errors, usage limits, and silent no-ops.

Agent Actions return their own errors and also pass through statuses from the core API, so the status code tells you which layer rejected a request. The sections below are organized by the status code you get back.

Read `err.statusCode` and `err.responseBody` on the `ClientError` rather than matching on message text. Agent Actions pass core API messages through unchanged, so the wording varies even when the cause doesn't.

> [!NOTE]
> A 401 is not a permissions problem
> A `401` means the token wasn't accepted at all. A valid token that lacks access to the target project returns `403` or `404`, and a malformed request returns `400`. Widening a token's project or dataset scope won't resolve a `401`.

## 401 Unauthorized

A `401` means the request carried no usable token. The causes are a missing `Authorization` header, a token that fails verification, and an expired session, which returns `Session expired`. Confirm the token reaches the client at runtime, then confirm it hasn't been revoked in [Manage](https://sanity.io/manage).

## 403 Forbidden

A `403` means the token is valid but the request isn't allowed. Two causes account for most of them:

- `AI features have been disabled at this organization's request.`: Returned with the message `Feature disabled.` when an organization has turned AI features off. An organization owner re-enables them in [Manage](https://sanity.io/manage). No change to the token or the request works around this.
- Project access: A token that can't see the target project returns the core API's own `403` or `404`, passed through unchanged. Check that the token belongs to the project named in the client's `projectId`.

## 400 Bad Request

A `400` means the request itself was malformed. These are the ones most often mistaken for authentication failures:

- `Invalid request body`: Returned with a details list naming the offending field, most often a missing `schemaId`.
- `Agent Actions are only available on apiVersion vX`: Agent Actions run only on `apiVersion: 'vX'`, and any dated API version is rejected.
- `Only bearer tokens are allowed as authorization`: The `Authorization` header uses a scheme other than `Bearer`.
- `Could not resolve projectId`: The request reached the API without a project ID. Set `projectId` on the client.

Every Agent Actions request needs `schemaId`. The client doesn't validate it, so omitting it is only a TypeScript error locally. Take the value from the output of `sanity schema deploy` or `sanity deploy`.

## 404 Not Found

`No deployed Studio schema found for` is returned when the target project and dataset have no deployed schema. Agent Actions read the deployed schema rather than your local files, so an undeployed change behaves exactly like a missing one. Run `sanity schema deploy` or `sanity deploy`, then pass the resulting `schemaId`.

## 429 Too Many Requests

`Plan or Budget Limit reached.` is returned when the plan or the Agent Actions budget is exhausted. Change either one in [Manage](https://sanity.io/manage). The response body includes `usageValue` and `quota`, so you can log how far past the limit the request was.

## Requests succeed but content is missing

### Text is generated but no image

With the AI Assist approach, an image whose type has no `imageInstructionField` configured is skipped. Generate writes the text fields and produces no image. The request succeeds and returns no error, so nothing reports the missing configuration.

Check two things: that the option is set on the image type, and that you deployed the schema after adding it. Generate reads the deployed schema, not your local files, so an undeployed change behaves exactly like a missing one. To skip schema configuration altogether, target the image's asset path directly.

## Related resources

[Agent Actions introduction](https://www.sanity.io/docs/agent-actions/introduction)
Requirements, core concepts, and limitations for Agent Actions.

[Create images with Agent Actions](https://www.sanity.io/docs/agent-actions/agent-actions-image-generation)
Set up image generation with explicit targets or with AI Assist.

[Agent Actions patterns](https://www.sanity.io/docs/agent-actions/agent-action-cheatsheet)
Common patterns and options shared by every Agent Action.