Error Reference

Common errors returned by TengineAI's MCP endpoint and management API, with causes and fixes.

---

MCP / Tool Execution Errors

These errors occur when the model attempts to connect or execute a tool.

HTTP Status	Error	Cause	Fix
401 Unauthorized	Invalid or inactive API key	The authorization_token in mcp_servers is wrong, revoked, or from a different project	Verify TENGINEAI_API_KEY matches the key in your project's Integrations tab
401 Unauthorized	Invalid member assertion	member_assertion JWT failed signature verification or has expired	Ensure exp ≤ 60s TTL, kid matches a registered assertion key, aud is tengine:project:<project_id>
401 Unauthorized	Member JWT has expired	The tng_mst_... session token is past its 15-minute TTL	Mint a new session token — see the caching pattern
403 Forbidden	Tool not enabled for this project	The model tried to call a tool that isn't enabled	Confirm is_enabled = true for the tool
403 Forbidden	member_external_id mode disabled in production	Using member_external_id field instead of member_assertion	Use member_assertion (customer-signed JWT) in production
403 Forbidden	Member context required	Tool has require_member: true but was called with a plain API key	Use a member session token (tng_mst_...)
500 Internal Server Error	Tool execution failed	TengineAI encountered an error calling your API endpoint	Check your server logs; verify your endpoint is reachable and returning valid responses
502 Bad Gateway	Upstream tool call failed	Your API returned a non-2xx response	Check your server logs; verify the endpoint path, method, and response format

---

Session Token Endpoint Errors

Errors from POST /api/v1/mcp/session-token:

HTTP Status	Detail	Cause	Fix
400 Bad Request	Provide member_assertion or member_external_id	Request body is empty or missing both fields	Include member_assertion in the request body
400 Bad Request	Could not resolve member_external_id	sub claim in the assertion is missing or not a string	Ensure sub is a non-empty string
400 Bad Request	API key missing project or integration	The API key isn't associated with an integration	Re-check the key; create it from an Integration, not from project settings
401 Unauthorized	Invalid or inactive API key	The API key in the Authorization header is wrong	Check TENGINEAI_API_KEY
401 Unauthorized	Invalid member assertion: MISSING_KID	JWT header is missing kid	Add headers={"kid": "your-key-id"} when encoding the assertion
401 Unauthorized	Invalid member assertion: KEY_NOT_FOUND	No active assertion key matches the kid	Register the public key first, or check the key is still active
401 Unauthorized	Invalid member assertion: AUD_MISMATCH	aud doesn't match tengine:project:<project_id>	Verify TENGINEAI_PROJECT_ID and construct aud as tengine:project:{project_id}
401 Unauthorized	Invalid member assertion: EXPIRED	Assertion JWT is past its exp	Mint a fresh assertion — keep TTL at 60s
401 Unauthorized	Invalid member assertion: INVALID_SIGNATURE	JWT was not signed with the registered private key	Verify the private key matches the public key registered for that kid

---

Custom Tool Errors

HTTP Status	Detail	Cause	Fix
400 Bad Request	Reserved variable cannot be provided as user input	Model passed member_id, project_id, or integration_id as a tool argument	Remove those from input_schema — they are auto-injected
400 Bad Request	base_url must use HTTPS	base_url uses http://	HTTPS is always required; use a tunnel (ngrok) to expose a local server
400 Bad Request	endpoint_path must start with /	Path template missing leading slash	Prepend / to the path
403 Forbidden	Member context required for this tool	Tool has require_member: true but the request used a plain API key	Authenticate with a member session token (tng_mst_...)
500 Internal Server Error	Failed to decrypt auth secret	encrypted_auth_secret is corrupted	Re-register the tool with a fresh secret value
500 Internal Server Error	Tool execution timed out	Your API endpoint did not respond within the timeout window	Check your server for slow queries or cold start latency; optimize the endpoint
502 Bad Gateway	Upstream tool call failed — non-2xx response	Your API returned an error status	Check your server logs; confirm the endpoint path, method, and auth are correct
502 Bad Gateway	Upstream tool call failed — connection error	Your API is unreachable	Confirm base_url is publicly accessible; check firewall/VPC rules

---

Tool Registration Errors

Errors from POST /api/v1/custom-tools:

HTTP Status	Detail	Cause	Fix
400 Bad Request	base_url must be origin-only (no paths)	base_url includes a path like /v1	Use origin only: https://api.example.com
400 Bad Request	encrypted_auth_secret is required when auth_strategy is 'hmac_signature'	Missing secret for a signed tool	Add encrypted_auth_secret to the tool config
400 Bad Request	endpoint_path uses {{member_id}} but require_member=False	Template references member ID without requiring a session	Set require_member: true
422 Unprocessable Entity	Validation error	Malformed JSON schema or invalid field value	Check the error detail for the specific field

---

Assertion Key Registration Errors

Errors from POST /api/v1/assertion-keys:

HTTP Status	Detail	Cause	Fix
400 Bad Request	Invalid public key format	PEM is malformed or wrong key type	Re-export: openssl ec -in private_key.pem -pubout -out public_key.pem
400 Bad Request	Unsupported algorithm	Algorithm not in ES256, ES384, Ed25519, RS256	Use a supported algorithm
409 Conflict	kid already exists for this project	A key with that kid is already registered	Use a different kid, or deactivate the existing key first

---

Debugging Tips

401 on a tool that was working — Your session token may have expired. Member session tokens have a 15-minute TTL. Implement the caching pattern in User-Scoped Quick Start to handle refresh transparently.

502 from a custom tool — Your API returned a non-2xx response. Add logging middleware to print all incoming requests and confirm your endpoint is receiving and handling the request correctly.

Signature verification failures — Print the canonical string your server constructs and compare it character-by-character with what TengineAI builds. Use the curl simulation in Build Your First Tool to test independently.

Model says it has no tools — The model can only see tools enabled for the project your token belongs to. Check is_enabled for each tool and confirm you're using the right API key for the right project.