docs: the spec calls the attempt failure_code machine-readable, the errors guide says do not branch on it #43

Page or section

Two places that disagree:

• API Reference, CallTaskAttempt.failure_code in openapi/calle.openapi.yaml
• Errors, the "Stable surfaces" table and the paragraph after it

Problem

The spec describes the attempt-level field like this:

failure_code: Machine-readable failure reason when this attempt failed.

Machine-readable means a machine reads it and does something different depending on what it says. That is what the words are for.

The errors guide says not to:

failure_code is a nullable string without a published enum

treat failure_code and failure_message as diagnostic context. Preserve the raw values for support, but do not branch retry, reporting, or analytics logic on a particular string.

The Calls API currently does not guarantee a distinct no-answer or callee-decline value at the call-task, recipient, or attempt level.

Both cannot be right. Either the attempt code is machine-readable, in which case the errors guide is too strict about the attempt level, or it is diagnostic context, in which case the spec should not call it machine-readable.

This is not a wording nitpick, because that field is the only place the ending of a call survives. On the calls I placed, the top-level failure_code came back call_failed every time, which only repeats the status, and failure_message came back NO ANSWER on both a line that rang for ninety seconds and a line that rejected the call in under half a second. The attempt code was 408 on the first and 486 on the second. It is the one field that tells them apart.

So a developer who reads the spec builds on the attempt code. A developer who reads the errors guide treats every failure as opaque and gives up information that is sitting right there. They will disagree in review, and both will have a quote.

Suggested improvement

Pick one, and say it in both places.

If the attempt code is meant to be branched on, publish what the values mean, even a partial list with a note that it may grow. 408 and 486 behaved exactly like the SIP codes they resemble on my calls, and if that is the intent it is worth stating rather than leaving people to infer it.

If it is not meant to be branched on, change the spec description to say so, and say what a caller should use instead to tell a no-answer from a busy line. Right now the guide says do not use it and does not offer an alternative, which leaves the question unanswerable.