Errors and retries - Digital Human API

The server client throws DigitalHumanApiError for HTTP, network, and invalid response failures.

import { DigitalHumanApiError } from "digital-human/server";

try {
  await client.createSession(options);
} catch (error) {
  if (error instanceof DigitalHumanApiError) {
    console.error(error.code, error.status, error.requestId);
  }
}

Error fields

Field	Description
`status`	HTTP status, or `0` for a network failure
`code`	Stable application error code when available
`requestId`	Identifier to include in support requests
`detail`	Structured response detail; do not expose blindly to users

Common statuses

Status	Typical action
`401`	Verify or rotate the server API key
`403`	Add the required key scope
`404`	Verify the session ID and the API key that created it
`409`	Use a new idempotency key for a different logical request
`422`	Correct the request body, header, or session ID
`503`	Retry later with bounded exponential backoff
`500`	Retry safely or contact support with the request ID

Retry create safely

Keep the idempotency key stable across retries:

const idempotencyKey = crypto.randomUUID();

await retryWithBackoff(() =>
  client.createSession({ idempotencyKey, digitalHumanId }),
);

Do not log request authorization headers or participant tokens while diagnosing errors.