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
{"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_REQUIRED401Cause: 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_KEY401Cause: 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_EXCEEDED429Cause: 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_ACTION200 (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_MISMATCH200 (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_REQUIRED200 (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_CREDITS200 (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
{
"success": false,
"error": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded (60 requests/minute). Please slow down.",
"retry_after_seconds": 60
}