Troubleshooting

Common issues when using ACE, what they mean, and how to fix them.

401 Unauthorized

What it means: the API did not accept your key. It is missing, malformed, inactive, or expired.

Send it correctly. Either Authorization: Bearer <your-api-key> or X-API-Key: <your-api-key>. Watch for stray whitespace. Keys begin with ace_live_ or ace_test_.
Check it in the dashboard. Under Settings, Developer console, Keys, confirm the key exists, is active, and has not expired. If you no longer have the full value, create a new key: the plain text is shown only at creation.
Check the base URL. Calling a v1 path on the wrong host fails auth before anything else runs.

The MCP endpoint (https://ace.authoritas.com/api/mcp) uses the same key in the same Authorization: Bearer <key> header.

403 Forbidden

What it means: the key is valid but lacks the scope for what you called, or the MCP tool is disabled for your project.

Read the message. It names the scopes that would satisfy the call, for example enrichment:write, admin.
Widen the key. Edit its scopes under Settings, Developer console, Keys, or create a key with what you need. New keys get enrichment:read, enrichment:write, and utils:read, which does not include webhooks: add webhooks:write to manage subscriptions.
For an MCP tool that reports being disabled, enable it under Settings, Developer console, MCP. Discovery always lists the full catalogue, so a tool can appear in tools/list and still be off for your project.

See API Keys for the full scope table.

402 Payment required

Two different causes share this status; the error code tells you which.

INSUFFICIENT_CREDITS means a live key has run the balance out.

Check with GET /api/v1/usage or the dashboard.
Add credits, or send a smaller batch.
Budget beforehand: cost is products × content types.

TEST_QUOTA_EXCEEDED means a test key has used its free monthly allowance. The testQuota block in GET /api/v1/usage shows what is left. Switch to a live key, or wait for the month to roll over.

SUBSCRIPTION_REQUIRED means the project bills through Shopify and the plan has not been approved. Approve it under Apps, Agentic Commerce Engine, Billing in your Shopify admin. See Credits and usage.

429 Rate limit exceeded

What it means: too many requests in a short window. Each key has a requests per minute limit.

Honour Retry-After. Back off exponentially if you are scripting.
Raise the limit on the key under Settings, Developer console, Keys.
Send fewer, larger requests. One /enrichment/pipeline call with 200 products costs one request; 200 single-product calls cost 200. Batch first.

A job is stuck or returned partial results

Large requests become durable jobs, so a 202 is normal rather than a failure.

Check its status: GET /api/v1/jobs/{id}, or ace jobs get <id>.
partial is a real outcome. Some products succeeded and some did not. GET /api/v1/jobs/{id}/results shows both, with succeededCount and failedCount. Retry only the failures.
Cancel a run you no longer want: POST /api/v1/jobs/{id}/cancel. Work already done is kept and still billed.
Do not double-pay for retries. Resend with the same Idempotency-Key and you get the original job back.

MCP: a tool is missing or fails

Confirm the server is reachable. An unauthenticated handshake should succeed:

curl -X POST https://ace.authoritas.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}'

Listing is public; calling is not. initialize, ping, and tools/list work without a key. Any tools/call without a valid bearer returns 401.
Tool disabled means it is off for your project. Enable it under Settings, Developer console, MCP.
Insufficient scope means the key cannot call that tool. See 403 above.
Merchant Center tools need a connected Google Merchant Center account, and catalog search needs an ingested catalog. Both are opt-in for that reason.

See MCP Server.

Connection errors or timeouts

Use the right base URL: https://ace.authoritas.com, no trailing slash. Sanity check with GET /api/v1/health, which needs no key.
Check the network path. Proxies and corporate firewalls sometimes block or rewrite requests.
Retry with backoff. If a synchronous call keeps timing out, send "mode": "async" and poll the job instead.

Output is empty or not what you expected

Check the request shape. Enrichment endpoints take a source ({ "type": "inline", "products": [...] } or { "type": "store", ... }), not a bare products array.
Send more signal. A product with only id and title gives the engine little to work with. Pass description, category, brand, price, images, and attributes where you have them.
Ground it in rules. Inconsistent tone across products usually means content was generated without shared rules. Derive them once with POST /api/v1/enrichment/rules and pass them into each content call. See Contextual Enrichment Engine and Generating content at scale.
Check readiness. POST /api/v1/utils/agentic-readiness is free and reports exactly which fields each product is missing.

Quick reference

Issue	Likely cause	Action
401	Missing, malformed, or expired key	Send `Authorization: Bearer <key>`; check the key is active.
403	Missing scope, or tool disabled	Widen the key's scopes, or enable the tool under Settings, Developer console, MCP.
402	Out of credits, test quota spent, or plan unapproved	Check `GET /api/v1/usage`; add credits, switch key, or approve the Shopify plan.
429	Too many requests	Honour `Retry-After`, raise the key limit, batch into fewer calls.
202 then silence	Work became a durable job	Poll `GET /api/v1/jobs/{id}` or subscribe to webhooks.
partial	Some products failed	Read `/jobs/{id}/results` and retry only the failures.
Connection or timeout	Wrong URL or network path	Check `GET /api/v1/health`; retry with backoff; use async mode.

For error shapes and rate limit headers, see the API Reference.

On this page