Troubleshooting

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

401 UnauthorizedCopy Anchor Link

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

1. 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_.
2. Check it in the dashboard. Under Settings, Developer console, Keys, confirm the key exists and has not been revoked or expired. A key you rotated stops working when its grace period ends. If you no longer have the full value, create a new key: the plain text is shown only at creation.
3. 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 ForbiddenCopy Anchor Link

What it means: the key is valid but is not allowed to do what you asked. The error code says which case you are in.

1. FORBIDDEN means the key lacks the scope the endpoint checks. The API Reference lists the scope for each endpoint. On the MCP server the message names the scopes the tool accepts and the ones your key has.
2. PROJECT_SCOPE_MISMATCH means the key is pinned to one project and the request named another. Use a key for that project, or an account-wide key.
3. Use a key with the right scopes. The console creates keys but does not edit them, so create a new key under Settings, Developer console, Keys with what you need. New keys get enrichment:read, enrichment:write, and utils:read. Webhooks, ratings, and feeds each need their own scope. See API Keys.
4. 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 requiredCopy Anchor Link

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

INSUFFICIENT_CREDITS means a live key has run the balance out.

1. Check with GET /api/v1/usage or the dashboard.
2. Ask your Rezolve Ai contact to add credits, or send a smaller batch.
3. Budget beforehand: cost follows the number of products and the content types you ask for. See Credits and usage for planning figures.

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 cannot run AI work yet. The message says why: the plan has not been approved, the store's setup is incomplete, or the store has reached its monthly budget. Open the Rezolve Ai app in your Shopify admin to approve the plan or finish setup, or raise the budget in the app's Settings. See Credits and usage.

429 Rate limit exceededCopy Anchor Link

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

1. Honour Retry-After. It is the number of seconds until the current one-minute window ends.
2. Know your limit. A live key allows 120 requests a minute unless it was created with a different limit, and a test key allows 20. X-RateLimit-Remaining on each response shows what is left. See Rate limits for how to set a different limit.
3. Send fewer, larger requests. One /enrichment/pipeline call with 200 products costs one request; 200 single-product calls cost 200. Batch first.

400 PROJECT_ID_REQUIREDCopy Anchor Link

What it means: you called an endpoint that returns one project's rows, such as GET /api/v1/feeds, with an account-wide key and did not say which project.

Add ?projectId=<id> to the request (ids come from GET /api/v1/projects), or use a key pinned to a project. See Project scope.

409 RUN_ALREADY_ACTIVECopy Anchor Link

What it means: a request that would start an enrichment run was refused because another run is already in progress for the project, started from the API, the app, a connected store or an assistant. Only one runs at a time, so the same products are never enriched and charged twice.

It applies to everything that starts a run:

• POST /api/v1/enrichment/pipeline, always.
• POST /api/v1/enrichment/content, when the request becomes a job (a 202). A small request that is answered inline is not a run and is not refused.
• The run_enrichment_pipeline and enrich_content MCP tools, which return the same message as the tool's error.

The message says where the run in progress was started, and details.runId and details.source name it. Wait for it to finish, then send the request again. The refusal costs nothing, and a test key's monthly allowance is not drawn.

A retry is never refused this way. Send the same Idempotency-Key as the request that started the run and you get that run's job back, even while it is still in progress.

A job is stuck or returned partial resultsCopy Anchor Link

Pipeline requests always become durable jobs, and so do large rules, content, and lookup requests, so a 202 is normal rather than a failure.

1. Check its status: GET /api/v1/jobs/{id}, or rezolve jobs get <id>.
2. 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.
3. Cancel a run you no longer want: POST /api/v1/jobs/{id}/cancel. Work already done is kept and still billed.
4. 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 failsCopy Anchor Link

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

   Copy Text

   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"}}}'

2. Listing is public; calling is not. initialize, ping, and tools/list work without a key. Any tools/call without a valid bearer returns 401.

3. Tool disabled means it is off for your project. Enable it under Settings, Developer console, MCP.

4. Insufficient scope means the key cannot call that tool. See 403 above.

5. "An enrichment run is already in progress" from run_enrichment_pipeline or enrich_content means the project already has a run going. See 409 RUN_ALREADY_ACTIVE above.

6. 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 timeoutsCopy Anchor Link

1. Use the right base URL: https://ace.authoritas.com, no trailing slash. Sanity check with GET /api/v1/health, which needs no key.
2. Check the network path. Proxies and corporate firewalls sometimes block or rewrite requests.
3. 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 expectedCopy Anchor Link

1. Check the request shape. Enrichment endpoints take a source ({ "type": "inline", "products": [...] } or { "type": "store", ... }), not a bare products array.
2. 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.
3. 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.
4. Check readiness. POST /api/v1/utils/agentic-readiness is free and reports exactly which fields each product is missing.

Quick referenceCopy Anchor Link

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