SupportAPI and MCP errors and troubleshooting
Diagnose Lead360 private integration authentication, rate, scope, operation, argument, approval, and execution errors without exposing tokens or probing other tenants.
How this fits into Lead360Explore the Lead360 platformConnect API and MCP access with the agency, tenant, scope, and risk model.- 01
HTTP error reference
- 02
MCP JSON-RPC and tool errors
- 03
Safe diagnostic record
- 04
Troubleshooting sequence
HTTP error reference
| Status | Typical code or condition | Resolution |
|---|---|---|
| 400 | Invalid request or content length | Validate method, JSON, fields, and header format |
| 401 | invalid_api_credential | Check Bearer format, active key, expiration, rotation, and stored secret |
| 403 | insufficient_scope or service_not_enabled | Review granted scopes, owner restrictions, and service entitlement |
| 404 | operation_not_found | Refresh discovery and verify the operation is authorized for this token |
| 409 | approval_required | Use a Lead360 draft and explicit approval instead of direct execution |
| 413 | Request body is too large | Keep the body under 256000 bytes and send only supported arguments |
| 422 | invalid_operation_arguments | Fetch the contract and correct missing, unexpected, forbidden, or invalid fields |
| 429 | rate_limit_exceeded | Honor Retry-After and reduce traffic |
| 502 | operation_execution_failed | Stop repeated calls, retain a redacted correlation record, and contact support |
| 503 | api_authentication_unavailable | Use bounded retry and contact support if the condition persists |
MCP JSON-RPC and tool errors
Malformed JSON-RPC requests return protocol errors such as Invalid Request, Invalid params, or Method not found. Tool-level policy and operation failures are returned inside a successful JSON-RPC result with content, structuredContent, and isError true. Check both the HTTP status and the MCP tool result.
- Use jsonrpc 2.0 and a string method.
- Send params as an object and include a tool name for tools/call.
- Use only initialize, ping, notifications/initialized, tools/list, and tools/call.
- Use only the documented fields for search, fetch, describe, and execute tools.
- Treat approval_required as a workflow boundary rather than a transport failure.
Safe diagnostic record
Record the timestamp, public key identifier, endpoint path, HTTP status, structured error code, operation key, client version, and a redacted summary of arguments. Never record the Authorization header, full token, secret, customer message content, payment details, or an unrestricted response body.
When contacting support, include whether the status endpoint succeeds, whether the operation appears in discovery, the risk and execution mode returned by fetch, and the exact error code. This gives support enough context without revealing credentials.
Troubleshooting sequence
- Call status with the same token and official app.lead360.io origin.
- Confirm the returned location and scopes match the approved integration.
- Read rate headers and stop when the key is exhausted.
- Search for the operation using the same credential.
- Fetch the current contract and compare risk, execution mode, and input schema.
- Remove forbidden or unexpected arguments and validate required values.
- Rotate the credential if exposure, truncation, or secret-storage corruption is possible.
- Contact Lead360 Support with redacted diagnostics when a reviewed adapter continues to fail.
Frequently asked questions
Why does MCP return HTTP 200 when a tool failed?
MCP tool errors can be represented in the JSON-RPC result with isError true. Inspect structuredContent and the error code.
Should I test another tenant identifier after operation_not_found?
No. The token tenant is fixed and tenant fields are rejected. Refresh discovery and review scopes for the authorized destination.
What information is safe to send to support?
Send timestamps, endpoint paths, public key IDs, status codes, operation keys, client versions, and redacted error bodies. Never send the private token or customer data.
Continue with Lead360
Use this workflow in Lead360
Put this guide into practice with a 14-day free trial of Lead360 Pro early access, or continue learning through the related collection.