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.

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:

score_issue_list entry

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

Field	Description
status	Severity of the signal (e.g. warning).
short_message	The machine-readable issue code (see below).
detail_message	A human-readable explanation.
source	Which part of scoring raised the issue (e.g. fluency, overall).

Issue codes

response_incomplete	fluency	Score Text (with include_fluency)	The attempt is incomplete — the recording may have been cut off or timed out.
response_freespeak	fluency	Score Text (with include_fluency)	The speaker is freely speaking outside the expected activity text.
response_no_speech	fluency	Score Text (with include_fluency)	No intelligible human speech is detected in the attempt.
response_too_short	overall	Score Speech	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.
error_word_count	answer content	Score Writing	The response is shorter or longer than the expected word count for the task_type (see Writing length). Scores are not reduced but a significantly lower word count can likely result in a lower score.
response_relevance_false	overall	Score Speech (with relevance_context)	The response is not relevant to the relevance_context. 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.
response_too_similar	overall	Score Speech (with relevance_context)	The response is too similar to the relevance_context. 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.

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.

Writing length by task type

Score Writing 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.