When the scoring call fails

POST /api/v1/score has a small, closed set of failures: seven status codes, one machine-readable error field, and two failure modes that never produce an error because they are recording problems rather than API problems — which include=quality now tells you about. This page is all of them, with the cause and the fix beside each one.

The status codes

Branch on the error string, not on the message. Messages are written for a human reading a log; the error field is the stable part, and it is what separates two cases that share a status code — a per-minute limit from a daily one, for instance.

The shape of an error body

Two shapes, and one exception. Validation failures use Laravel's field-keyed form: a message and an errors object naming each field that failed. Everything else carries a message plus a machine-readable error string, and sometimes a field specific to that failure. The exception is the 413, which is produced by the web server before the API runs and is therefore not JSON at all.

422 — validation

HTTP/1.1 422 Unprocessable Content

{
  "message": "The audio field is required.",
  "errors": {
    "audio": ["The audio field is required."]
  }
}

The errors object is where the useful part lives; message is only the first of them. Read the keys, not the prose. One validation case has its own wording, because it is common enough to deserve a message a user could almost read:

HTTP/1.1 422 Unprocessable Content

{
  "message": "That recording came through empty. Please try again.",
  "errors": {
    "audio": ["That recording came through empty. Please try again."]
  }
}

401 and 403 — credentials

HTTP/1.1 401 Unauthorized

{
  "message": "This endpoint requires an ArticScore API key. Send it as: Authorization: Bearer <key>",
  "error": "api_key_required"
}

HTTP/1.1 403 Forbidden

{
  "message": "This API key is not permitted to use this endpoint (missing ability "api:score").",
  "error": "insufficient_scope",
  "required_ability": "api:score"
}

429 — rate limits

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: <your per-minute limit>
X-RateLimit-Remaining: 0

{
  "message": "Too many scoring requests. This API key is limited to <n> requests per minute.",
  "error": "rate_limit_exceeded",
  "retry_after_seconds": 37
}

error is rate_limit_exceeded for the per-minute burst window and daily_quota_exceeded for the daily cap. Both limits are per key. GET /api/v1/info reports the ones in force for yours, and needs no key to call — so a client can enforce them on its own side instead of discovering them the hard way.

502 — the engine did not answer

HTTP/1.1 502 Bad Gateway

{
  "message": "Pronunciation scoring failed. Please try again.",
  "error": "scoring_failed",
  "request_id": "9f2b1c84-1f2a-4d5e-9a77-0c3b6e5d4a10",
  "detail": null
}

detail is always null in production. The request_id is the part to keep: it identifies the exact scoring run in our logs.

Cause and fix

The two failures that return 200

These are the ones that cost the most time, because nothing in the scores says anything went wrong. Both are recording problems, and from the API's side nothing failed: it was handed audio and a target text, and it scored the one against the other.

Ask for include=quality and you are told. The response gains a quality block, and quality.usable is false when the recording had no speech (reason: "no_speech"), sounded like a different word (wrong_word), carried extra voices or words (extra_speech), was cut off (cut_off) or held only part of the word (incomplete). When it is false, show “let’s try again”, never the score. The checks were validated on synthetic failures built from children’s read speech (speechocean762), not yet on children with speech sound disorders, so the advice below still applies. The quality block.

There is no speech in the recording

A completely empty upload is caught — it comes back 422 with That recording came through empty. Please try again. But a file that contains bytes and no audible speech is a valid recording as far as the API is concerned. It gets scored, and what comes back is a real response at the floor, typically with omissions, which is exactly what a genuinely terrible production would also look like. There is no way to tell the two apart from the scores; quality reports it as no_speech.

• chevron_rightCheck the level before you upload. Decode the blob and look at its amplitude, or watch an AnalyserNode while recording. A take with no signal in it is worth discarding client-side.
• chevron_rightDiscard very short takes. Under about half a second is a mis-tap, not an attempt.
• chevron_rightSuspect the constraints on Apple devices. Safari's noiseSuppression and autoGainControl can hand back audio so quiet it is effectively silent. Our own product asks for channelCount: 1 and nothing else there.
• chevron_rightCheck the microphone actually opened. A permission race produces a zero-byte blob, which is the 422 case - but a stream that opened on the wrong device produces a real file of near-silence, which is this one.

The audio does not match the text you sent

The expected phoneme sequence is derived from text and aligned against the audio. If the two do not correspond — the child said a different word, the prompt advanced before the recording did, the text carries a word the speaker never attempted — the engine still aligns the sequence it was given against the audio it was given. The result is a well-formed response full of numbers that mean nothing.

• chevron_rightCompare the echoed text against the prompt. The response returns the target text, normalised. If your prompt and that string can ever disagree, they eventually will.
• chevron_rightWatch for empty extent arrays. extent is [start_ms, end_ms] when timing was reported for a phoneme and empty when it was not. A response where timing is thin is worth a listen.
• chevron_rightBeware of off-by-one prompts. The most common version of this bug is a UI that advances the target word while the previous recording is still uploading. Capture the target at record time and send that captured value, not whatever is on screen when the upload fires.
• chevron_rightRemember there is no transcription. The engine is not an open-vocabulary recogniser and will not tell you what the speaker said instead. With include=quality it will tell you that it did not sound like the target (wrong_word); to ask which of a few known words was said, send them as choices.

Timeouts and retries

Scoring normally returns in about a second. A 30-second client timeout is a reasonable ceiling: long enough that nothing healthy trips it, short enough that a child is not left watching a spinner. Time out on your side rather than waiting indefinitely, and keep the recording so a retry does not mean recording again.

There is no idempotency key. A retry is a new scoring request: it is scored again and it counts against your rate limit again. That makes an aggressive retry loop the fastest route to a 429, so back off on failure rather than hammering. A refused 429 itself was never scored and was not counted against anything else.

What to include in a support request

• chevron_rightThe request_id. Every scored response and every 502 carries one. It is the handle to the exact scoring run in our logs, and it is the single most useful thing you can send.
• chevron_rightThe time, with a timezone. Roughly when, if you cannot be exact.
• chevron_rightThe status code and the whole JSON body, not a paraphrase. The error field distinguishes cases that look identical from the outside.
• chevron_rightThe exact text you sent. Including capitalisation and punctuation — the expected phoneme sequence is derived from it.
• chevron_rightThe audio's format, size and duration, plus the browser and device it was recorded on. Most reports that turn out to be recording bugs are diagnosed from this line alone.
• chevron_rightWhether it reproduces, and how often. Three in five is a different investigation from one in a thousand.
• chevron_rightNot the recording. We do not need it and we would rather not have it. Partner audio is scored and dropped — never retained, never used for training, never tied to a persistent identifier for the speaker — and the request_id means we can find the call without it.

request_id:   9f2b1c84-1f2a-4d5e-9a77-0c3b6e5d4a10
when:         2026-08-28 14:07 UTC
status:       502
body:         {"message":"Pronunciation scoring failed. Please try again.",
               "error":"scoring_failed","request_id":"9f2b...","detail":null}
text sent:    "rabbit"
audio:        audio/webm;codecs=opus, 41 KB, ~1.4 s, Chrome 141 on Android
reproducible: 3 of 5 attempts in the last hour, same key
what I expected: a scored response

Send it through our contact page, or paste it into the support chat in the corner of any page. If the problem turns out to be in your recording pipeline rather than in ours — which is where a good share of them are — audio requirements is the page that covers it.