Coze API Debugging Guide: Fixing Common /run Endpoint Errors Step by Step

Core question: Why does a simple Coze /run API request keep failing, and how can you systematically debug and fix it?

This guide walks through a real-world debugging process of calling the Coze /run API. It covers the most common failure patterns—missing parameters, empty request bodies, invalid JSON formatting, and double-encoded payloads—and explains how to resolve them with precise, reproducible fixes.

The goal is not just to fix one error, but to give you a structured approach to diagnosing API issues efficiently.

---

1. Why Does a Simple API Call Fail Repeatedly?

Core question: Why does a basic HTTP POST request trigger multiple different errors during debugging?

Consider this initial request:

curl --location 'https://wmyy9nzp6c.coze.site/run' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "query": "Hello",
    "user_id": "test_user_001"
}'

The response:

{
  "detail": {
    "error_code": 201001,
    "error_message": "Missing required field: user_input"
  }
}

After fixing that, new errors appear:

• ContentLength=49 with Body length 0
• Invalid JSON format
• 400 Bad Request

This pattern is typical:

• Each fix reveals a new issue
• The request “looks correct” but still fails
• Errors shift rather than disappear

This is not unusual—it’s how strict API validation behaves.

---

2. Error Type #1: Missing Required Field (user_input vs query)

Core question: Why does the API say a field is missing even though I passed one?

❌ Incorrect Request

{
  "query": "Hello",
  "user_id": "test_user_001"
}

✅ Correct Request

{
  "user_input": "Hello",
  "user_id": "test_user_001"
}

---

Root Cause

The backend enforces strict schema validation, similar to:

class TopicPlanningInput(BaseModel):
    user_input: str

Implications:

• Field names must match exactly
• No aliasing or fallback
• Unknown fields (like query) are ignored

---

Scenario

This issue commonly appears when:

• Frontend uses query
• Backend or workflow expects user_input
• No mapping layer exists

---

Insight

This is not a missing data problem—it’s a schema mismatch problem.

---

3. Error Type #2: Empty Request Body (Body length 0)

Core question: Why is my request body empty even though I defined it?

Example error:

{
  "$error": "ContentLength=49 with Body length 0"
}

---

What It Means

• The client declared a body size
• But sent nothing

The server rejects the request immediately.

---

Common Mistake

{
  "body": {
    "user_input": "Hello"
  }
}

…but the tool never actually sends it.

---

✅ Correct Example (Node.js)

fetch("https://wmyy9nzp6c.coze.site/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    user_id: "test_user_001",
    user_input: "Hello"
  })
})

---

Scenario

This occurs frequently in:

• Low-code platforms
• Improper HTTP client usage
• Missing serialization in backend code

---

Insight

Defining a body is not enough.

Only a serialized payload (e.g., JSON string) is actually transmitted.

---

4. Error Type #3: Invalid JSON Format

Core question: Why does valid-looking JSON fail to parse?

Example error:

Invalid JSON format
Expecting property name enclosed in double quotes

---

❌ Common Invalid JSON

Single quotes

{
  'user_input': 'Hello'
}

Missing quotes

{user_input: Hello}

Non-JSON structures

map[user_input:Hello]

---

✅ Correct JSON

{
  "user_input": "Hello"
}

---

Scenario

This often happens when:

• Writing JSON manually
• Using string concatenation
• Misconfigured templating systems

---

Insight

JSON is strict:

It must be syntactically valid—not just visually similar.

---

5. Error Type #4: Double-Encoded JSON (String Instead of Object)

Core question: Why does correctly escaped JSON still fail?

❌ Incorrect Payload

"body": "{\\\"user_input\\\":\\\"123\\\"}"

---

What Is Actually Sent

"{\"user_input\":\"123\"}"

This is:

• A string
• Not a JSON object

---

❌ Wrong Pattern

"body": "..."

---

✅ Correct Pattern

"body": {
  "user_id": "test_user_001",
  "user_input": "123"
}

---

Scenario

Common in:

• Platforms that auto-serialize data
• Developers manually applying JSON.stringify
• Double encoding in pipelines

---

Insight

This is a subtle but critical mistake:

You think you’re sending JSON—but you’re sending a string.

---

6. Fully Working Request Example

Core question: What does a correct Coze API request look like?

{
  "url": "https://wmyy9nzp6c.coze.site/run",
  "method": "POST",
  "header": {
    "Authorization": "Bearer {{COZE_TOKEN}}",
    "Content-Type": "application/json"
  },
  "body": {
    "user_id": "test_user_001",
    "user_input": "Hello"
  }
}

---

7. Understanding the Response

Successful response:

{
  "publish_links": {
    "Douyin": "...",
    "WeChat Channels": "...",
    "Kuaishou": "...",
    "Bilibili": "..."
  },
  "run_id": "xxxx"
}

---

Field Breakdown

Field	Description
publish_links	Platform-specific output links (often placeholders)
run_id	Unique execution identifier

---

Scenario

Useful for:

• Content distribution pipelines
• Multi-platform publishing workflows
• Async task tracking

---

8. Practical Debugging Checklist

Core question: How do I quickly identify what’s wrong?

Use this checklist:

• [ ] Are you using user_input (not query)?
• [ ] Is body a JSON object (not a string)?
• [ ] Are all keys and values using double quotes?
• [ ] Did you call JSON.stringify (if required)?
• [ ] Is the request body actually being sent?
• [ ] Is there any extra wrapping (e.g., { body: {...} })?

---

9. Error Reference Table

Error Type	Symptom	Root Cause
Missing field	user_input missing	Wrong field name
Empty body	Body length 0	Payload not sent
JSON parse error	Invalid JSON	Bad syntax
Double encoding	JSONDecodeError	String instead of object

---

10. One-Page Summary

• Use exact field: user_input
• Ensure body is a JSON object
• Use double quotes only
• Avoid double encoding
• Confirm payload is actually sent

---

11. FAQ

1. Why doesn’t query work?

Because the API strictly requires user_input.

---

2. Why is my body empty?

Your HTTP client is not sending the payload properly.

---

3. Why does valid JSON fail?

It may contain syntax issues like single quotes or missing quotes.

---

4. What is double encoding?

Sending JSON as a string instead of an object.

---

5. How can I verify my request body?

Log the outgoing payload—it should look like:

{"user_input":"Hello"}

---

6. What is run_id used for?

Tracking execution status and results.

---

7. Are the returned links real?

Usually placeholders unless real integrations are configured.

---

Final Takeaway

Coze API issues are rarely about complexity—they are about strict correctness.

If you ensure:

• Exact field names
• Proper JSON structure
• Actual payload transmission

…you will eliminate most integration errors.

Understanding these patterns is more valuable than memorizing fixes.