40001: Assignment Instruction response is not valid JSON. Ensure it is not escaped

TaskRouter

Description

This error occurs when TaskRouter receives an Assignment Instruction response that is not valid JSON. A common cause is returning a JSON string that has been escaped instead of returning a raw JSON object in the HTTP response body.

TaskRouter expects your Assignment Callback or related instruction-generating endpoint to respond with properly formatted JSON. If the payload is double-encoded, escaped, malformed, or returned with unexpected formatting, TaskRouter cannot parse it and raises error 40001.

Example

Valid JSON (Not Escaped)

1{
2  "instruction": "call",
3  "from": "+15558675309",
4  "url": "http://example.com/agent_answer",
5  "status_callback_url":
6    "http://example.com/agent_answer_status_callback"
7}

Invalid JSON (Escaped)

{\r\n  \"instruction\": \"call\",\r\n  \"from\": \"+15558675309\",\r\n  \"url\": \"http:\/\/example.com\/agent_answer\",   \r\n  \"status_callback_url\":\r\n    \"http:\/\/example.com\/agent_answer_status_callback\"\r\n}

Possible causes

Your application returns JSON as an escaped string instead of a JSON object.
The response body is being serialized twice before being sent.
Your web framework is wrapping the JSON payload in quotes.
The callback handler is returning text or HTML instead of JSON.
The response contains malformed JSON syntax, such as missing braces, commas, or quotes.
The endpoint is setting an unexpected response format or content type for the Assignment Instruction response.

Possible solutions

Return a raw JSON object in the HTTP response body, not a stringified or escaped JSON value.
Check your server code for double serialization, such as calling JSON encoding on data that has already been encoded.
Verify that your Assignment Callback response is valid JSON by testing the endpoint directly.
Confirm your application returns the expected Content-Type header, such as application/json, when sending Assignment Instructions.
Review framework-specific response helpers to ensure they serialize the payload only once.
Inspect logs or captured HTTP responses to confirm the response body matches the expected JSON structure.