MCP

# Error Reference

Every error the Synter MCP server returns, what causes it, and how to fix it

Most errors are in the response body, not the HTTP status

Only auth (401) and rate limiting (429) use a non-200 HTTP status. Tool-level failures — an unknown action, a mismatched target, a missing consent flag, an insufficient balance — come back as a 200 response with `{"success": false, ...}` in the body, so check the `success` field, not just the status code. The exact shape isn't fully uniform across error types, though: most carry the code in `error`, but a few (noted below) carry it in `error_code` or `code` instead — check each entry's status column rather than assuming one field name everywhere.

`AUTHENTICATION_REQUIRED` 401

**Cause:** No X-Synter-Key header (or bearer token) was sent at all.

**Fix:** Add the header — see Configuration for the exact shape per client.

`INVALID_API_KEY` 401

**Cause:** An X-Synter-Key header was sent, but it's malformed (keys always start with syn\_) or doesn't match an active key.

**Fix:** Copy a fresh key from the Developer Portal and re-check your client config — see Configuration.

`RATE_LIMIT_EXCEEDED` 429

**Cause:** Your client sent more requests than the courtesy rate limiter allows in the current window.

**Fix:** Back off and retry — the response body includes retry\_after\_seconds. See Rate Limits & Credits.

`UNKNOWN_ACTION` 200 (error in body)

**Cause:** execute() was called with an action name that isn't registered in the script library — a typo, or a script that was renamed/removed. (A self-hosted MCP server running in direct mode returns the bare string "Unknown action: <name>" instead of this code — same cause, different shape.)

**Fix:** Call list\_available\_scripts to see every valid action name, or inspect\_script to confirm the exact spelling before calling execute.

`TARGET_MISMATCH` 200 (error in body)

**Cause:** execute() was called with expected\_names set (e.g. {"campaign-id": "Brand\_Leaders"}) and the live entity's actual name didn't match — or couldn't be resolved to check at all.

**Fix:** Confirm you have the right campaign/ad-group/ad ID before retrying. This guard exists specifically to stop an agent from acting on the wrong entity — don't loosen it by omitting expected\_names to make an error go away.

`PII_CONSENT_REQUIRED` 200 (error in body — carried in error\_code, not error)

**Cause:** sync\_audience or stage\_audience\_artifact was called without i\_have\_consent=true. Synter requires explicit confirmation that you have lawful basis (GDPR Art. 6) and platform Customer Match consent for every identifier you upload.

**Fix:** Pass i\_have\_consent=true only once you've actually confirmed that basis with your legal/compliance process — this isn't a formality to click through.

`INSUFFICIENT_CREDITS` 200 (error in body — carried in code, not error)

**Cause:** Your account's credit balance is lower than the tool's cost, or you've hit your daily spend cap.

**Fix:** Check get\_credit\_balance (free) to see your balance and the specific tool's cost, then top up or wait for the daily cap to reset.

## Example error body

json

```
{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded (60 requests/minute). Please slow down.",
  "retry_after_seconds": 60
}
```

Was this page helpful?

YesNo

[Previous Rate Limits & Credits](https://docs.syntermedia.ai/mcp/rate-limits) [Next MCP Server Launch](https://docs.syntermedia.ai/changelog/mcp-server-launch)

---

Source: https://docs.syntermedia.ai/mcp/errors
Full docs as one file: https://docs.syntermedia.ai/llms-full.txt