Skip to content
Legato Docs

Errors Reference

This page documents the LegatoError interface and the stable error-code literals used by the Legato boundary.

LegatoError interface

Section titled “LegatoError interface”

Error payload shape used by playback-error events and API failures.

interface LegatoError {
  /** Stable machine-readable code. */
  code: LegatoErrorCode;
  /** Human-readable error message from adapter/runtime. */
  message: string;
  /** Optional transport-specific details. */
  details?: unknown;
}

Error codes

Section titled “Error codes”

LEGATO_ERROR_CODES

Section titled “LEGATO_ERROR_CODES”

All supported error code literals.

import { LEGATO_ERROR_CODES } from '@ddgutierrezc/legato-contract';


// LEGATO_ERROR_CODES = [
//   'player_not_setup',
//   'invalid_index',
//   'empty_queue',
//   'no_active_track',
//   'invalid_url',
//   'load_failed',
//   'playback_failed',
//   'seek_failed',
//   'unsupported_operation',
//   'platform_error'
// ];

Error code matrix

Section titled “Error code matrix”
CodeObservable meaningNotes / source
player_not_setupA player operation was rejected because setup preconditions were not met.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
invalid_indexAn index-based operation was rejected.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
empty_queueAn operation required queue items, but queue preconditions were not met.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
no_active_trackAn operation required an active track, but none was active.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
invalid_urlA media URL input was rejected.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
load_failedA media load phase failed.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
playback_failedPlayback execution failed after or during start.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
seek_failedA seek request failed.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
unsupported_operationThe requested operation is not supported by the runtime in current conditions.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).
platform_errorA platform/native-layer error was surfaced through the boundary.Stable literal in LEGATO_ERROR_CODES (packages/contract/src/errors.ts).

Stability model

Section titled “Stability model”
  • Treat error.code as the machine-stable discriminator.
  • Treat error.message as human-readable runtime text that may vary by adapter, platform, or native source.
  • Treat error.details as optional transport-specific payload (unknown by contract).
function classify(error: LegatoError) {
  switch (error.code) {
    case 'unsupported_operation':
      return 'capability-gated';
    case 'invalid_index':
      return 'input-shape';
    default:
      return 'other';
  }
}

Handling errors

Section titled “Handling errors”

Via event listener

Section titled “Via event listener”
import { onPlaybackError } from '@ddgutierrezc/legato-capacitor';


onPlaybackError(({ error }) => {
  console.error('Playback error:', error.code, error.message);
  if (error.details) {
    console.error('Details:', error.details);
  }
});

Via async error handling

Section titled “Via async error handling”
try {
  await audioPlayer.play();
} catch (err) {
  if (err.code) {
    console.error('Legato error:', err.code);
  } else {
    throw err;
  }
}
Section titled “Related types”