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.

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.

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. 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.

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.

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.

Plan or Budget Limit reached. is returned when the plan or the Agent Actions budget is exhausted. Change either one in Manage. The response body includes usageValue and quota, so you can log how far past the limit the request was.

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.