Integrate the SDK

Errors

When something fails in a session — while it starts, while it runs, or when a request you made is rejected — it reaches your code as one typed error. You catch it, explain it to the user in your own words, and branch on it; every code it can carry is listed below.

The error object

Every error is one object:

Two messages, for two readers

Every error carries both, and they are not interchangeable. userMessage is written for the person using your app and arrives already translated into the session's language, so you can put it on screen as it is. message is English and written for you: it names options, settings and values, and belongs in a log, not in your UI.

// Show one, log the other.
showBanner(error.userMessage);              // translated, for the person
log.error(error.code, error.message);       // English, for you
// Reporting a problem? Quote the id of the answer it came from.
log.error("reference", session.getState().requestId);

Set the language with uiLanguage, on createClient or on a single session. Leave it unset and Speechineer picks the one the browser asked for.

The id to quote

state.requestId is the id of the most recent answer. It belongs to the call rather than to any one error, which is why it sits on the state and not on the error. The same id follows that request through every part of Speechineer that handled it — so quoting it in a bug report is the difference between us guessing and us looking.

Categories and classes

Every error also belongs to a category, and each category has its own class. Catch the class to handle a whole family at once — SpeechineerQuotaError covers every way an allowance can run out — or read error.code when you need the specific cause:

The numbers on a quota error

A quota error is the one category that carries figures, on error.meta. The keys are the same whether the allowance ran out on the request that started the session or while it was running, so one piece of code renders both:

Listen for errors

However a session fails, you never have to hunt for the error: the same object is delivered to three places, each suited to a different job — a callback for reacting the moment something fails, the session state for rendering, and the rejected promise for the code that asked. Use whichever fits the code you are writing.

• The onError callback — called the moment it happens. Log the error or send it to analytics from there:
  ReactAngularJavaScript

  tscopy

  const voice = useSpeechToForm({
    form: intakeForm,
    onError: (error) => showBanner(error.code),
  });

• The session state — the failure sits in errors (the first entry is the one to show) and stays until the next start(). Render your message from there — describe is your own mapping from a code to your wording:
  ReactAngularJavaScript

  tsxcopy

  {voice.errors.length > 0 && <p role="alert">{voice.errors[0].userMessage}</p>}

• The rejected promise — start() and end() reject with the same error, so an await where you call them catches it directly:
  ReactAngularJavaScript

  tsxcopy

  const onSpeak = async () => {
    try {
      await voice.start();
    } catch (error) {
      showBanner(error.code);
    }
  };

Error codes

One section per category, so a section is exactly what one catch gives you: the class in the heading is what instanceof matches, and the codes under it are every way that class can arrive. The codes are frozen — they will not change under you.