> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/interpreting-results/scoring-errors-and-warnings.md).

# Scoring errors & warnings

Some signals are returned **inside an otherwise successful score** rather than as a request-level error. A request can succeed (HTTP `200`, status `success`, a score is returned) and still tell you the attempt may not be suitable for a reliable evaluation of the speaker — for example the speaker didn't follow the script, said nothing intelligible, or wrote far too little. This page covers those in-response signals: the **`score_issue_list[]`** array.

For request-level failures (missing parameters, bad audio, unsupported features, etc.), see [Error Handling](/getting-started/error-handling.md).

## score\_issue\_list

When the API detects a problem with an attempt that lowers confidence in the score, it reduces the affected scores and appends an entry to `score_issue_list[]`. Each entry has the same shape:

{% code title="score\_issue\_list entry" %}

```json
"score_issue_list": [
  {
    "status": "warning",
    "short_message": "response_incomplete",
    "detail_message": "The response doesn't follow the script completely.",
    "source": "fluency"
  }
]
```

{% endcode %}

<table><thead><tr><th width="213.359375">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td>Severity of the signal (e.g. <code>warning</code>).</td></tr><tr><td><code>short_message</code></td><td>The machine-readable issue code (see below).</td></tr><tr><td><code>detail_message</code></td><td>A human-readable explanation.</td></tr><tr><td><code>source</code></td><td>Which part of scoring raised the issue (e.g. <code>fluency</code>, <code>overall</code>).</td></tr></tbody></table>

### Issue codes

<table data-header-hidden><thead><tr><th width="196.5390625">short_message</th><th>source</th><th>Raised by</th><th>Meaning</th></tr></thead><tbody><tr><td><code>response_incomplete</code></td><td><code>fluency</code></td><td><a href="/api-reference/score-text.md">Score Text</a> (with <code>include_fluency</code>)</td><td>The attempt is incomplete — the recording may have been cut off or timed out.</td></tr><tr><td><code>response_freespeak</code></td><td><code>fluency</code></td><td><a href="/api-reference/score-text.md">Score Text</a> (with <code>include_fluency</code>)</td><td>The speaker is freely speaking outside the expected activity text.</td></tr><tr><td><code>response_no_speech</code></td><td><code>fluency</code></td><td><a href="/api-reference/score-text.md">Score Text</a> (with <code>include_fluency</code>)</td><td>No intelligible human speech is detected in the attempt.</td></tr><tr><td><code>response_too_short</code></td><td><code>overall</code></td><td><a href="/api-reference/score-speech.md">Score Speech</a></td><td>The response is shorter than the minimum expected 20 words for Score Speech. Overall score is reduced to zero, but all other scores are preserved.</td></tr><tr><td><code>error_word_count</code></td><td><code>answer content</code></td><td><a href="/api-reference/score-writing.md">Score Writing</a></td><td>The response is shorter or longer than the expected word count for the <code>task_type</code> (see <a href="#writing-length-by-task-type">Writing length</a>). Scores are not reduced but a significantly lower word count can likely result in a lower score.</td></tr><tr><td><code>response_relevance_false</code></td><td><code>overall</code></td><td><a href="/api-reference/score-speech.md">Score Speech</a> (with <code>relevance_context</code>)</td><td>The response is not relevant to the <code>relevance_context</code>. The overall score is set to zero. The Pronunciation, Fluency, Grammar, Vocab, Coherence scores are preserved but may be unusable given that the speaker did not address the intended prompt.</td></tr><tr><td><code>response_too_similar</code></td><td><code>overall</code></td><td><a href="/api-reference/score-speech.md">Score Speech</a> (with <code>relevance_context</code>)</td><td>The response is too similar to the <code>relevance_context</code>. The overall score is set to zero. The Pronunciation, Fluency, Grammar, Vocab, Coherence scores are preserved but may be unusable given that the speaker did not address the intended prompt.</td></tr></tbody></table>

{% hint style="info" %}
Treat a `score_issue_list` warning as a signal to **ask the user to try again** rather than to show a (reduced) score — the score is intentionally lowered and is not a fair reflection of ability.
{% endhint %}

## Writing length by task type

[Score Writing](/api-reference/score-writing.md) expects the `answer` length to fall within the range for its `task_type`. When the word count falls outside that range, the API adds a `score_issue_list[]` warning and the scores are reduced.

| `task_type`     | Expected length |
| --------------- | --------------- |
| `essay-writing` | 150 – 300 words |
| `short-writing` | 50 – 100 words  |
| `chat-writing`  | 50 – 100 words  |

Keep submissions within the expected range for a representative score.