Schema mismatch errors (DELX-4001) occur when the payload your agent sends does not match the expected input schema for a tool. This is one of the most common integration errors and is usually straightforward to resolve once you identify which field is wrong.
Symptoms
Tool calls return DELX-4001 error codes with "invalid input schema" in the response body
A tool that works in one environment (e.g. local dev) fails in another (e.g. production) with validation errors
Parameter types do not match expected schema -- for example, sending a string where a number is required
Required fields are missing from the payload, or extra unrecognized fields cause strict validation to reject the request
Enum values do not match the allowed set (e.g. sending "high" when the schema expects "elevated")
Root causes
The most common cause is using an outdated cached schema that no longer matches the current API version. Other causes include inconsistent field naming conventions (e.g. sessionId vs session_id), controller payloads that bypass client-side pre-validation, and schema differences between the REST and MCP endpoints for the same tool.
Step-by-step fix
Fetch the current schema. Use the get_tool_schema MCP tool or call the REST endpoint to retrieve the latest schema definition for the tool that is failing.
Compare your payload against the schema. Diff the fields, types, and required properties. Look for renamed fields, changed types (string to number), or new required fields.
Check required vs optional fields. Ensure every required field is present. Remove any fields not defined in the schema if strict validation is enabled.
Verify enum values match exactly. Enum comparisons are case-sensitive. Check that your values are in the allowed set listed in the schema.
Test with a minimal valid payload. Strip your request down to only the required fields with known-good values. If this works, add fields back one at a time to isolate the mismatch.
Check your API version. Schema definitions may change between versions. Confirm which version your agent is targeting and ensure the schema you are validating against is from the same version.
Code example
First, inspect available tools and their schemas:
# List all tools with minimal output
curl "https://api.delx.ai/api/v1/tools?format=minimal"
# Get full schema for a specific tool via MCP
curl -X POST https://api.delx.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_tool_schema",
"arguments": { "tool_name": "wellness_check" }
},
"id": 1
}'
Compare the returned schema against your payload. Pay close attention to required arrays and type definitions for each property.
Prevention
Always fetch the schema before the first call. At agent startup, retrieve current schemas rather than relying on a hardcoded copy. Cache them for the duration of the session but refresh on restart.
Pin to an API version. Use versioned endpoints or include a version header so that schema changes in newer versions do not break your existing integration.
Validate payloads client-side before sending. Run your payload against the fetched JSON Schema locally. This catches mismatches before they hit the API and produces clearer error messages for debugging.
Validation
Re-run the failing payloads against the current schema after applying your fix. Confirm that: (1) the response no longer contains DELX-4001, (2) the tool returns the expected result structure, and (3) the fix works in all environments (dev, staging, production). Add a schema validation step to your CI pipeline to catch future mismatches early.
