Error Handling

The SDK surfaces separate HTTP, validation, socket decode, and transport failure channels. Catch the specific channel you expect.

EngineHttpError

Thrown by any HTTP method on SimulatorClient when the server responds with a non-2xx status. The body is parsed against the api-error-response schema before the error is thrown.

import { EngineHttpError, createSimulatorClient } from '@my-swu/simulator-client'

const simulatorClient = createSimulatorClient({ baseUrl: 'http://127.0.0.1:4000' })

try {
  // Missing matches demonstrate the non-2xx HTTP error path.
  await simulatorClient.matches.get('missing-match')
}
catch (error) {
  if (error instanceof EngineHttpError) {
    // Prefer structured fields over parsing the message string.
    console.warn(error.status, error.code, error.method, error.url, error.message)
  }
}

Fields:

• status — HTTP status code.
• code — engine error code (for example match_not_found).
• method — HTTP method used for the request.
• url — fully resolved request URL.
• payload — parsed JSON body when available.
• responseText — raw body text when available.
• message — human-readable message from the engine.

Common deck and format codes:

• invalid_selection — deck shape or gameplay choice failed validation. The message names the exact rule, such as sideboard size or copy count.
• unsupported_format — requested match format or player count is schema-valid but not supported by the current runtime.

SdkValidationError

Thrown by parseSchema when an outbound payload does not match the generated schema. The SDK HTTP methods validate request bodies before sending, and the session socket validates every outbound envelope.

import { SdkValidationError } from '@my-swu/simulator-client'

try {
  // Outbound payload validation fails before anything is sent.
  matchSession.sendCommand(/* malformed */ {} as never)
}
catch (error) {
  if (error instanceof SdkValidationError) {
    // Details include schema paths that are useful for developer logs.
    console.warn(error.schemaName, error.details)
  }
}

Fields:

• schemaName — the schema the payload failed against.
• details — list of path + message strings from Ajv.

Socket-side decoding failures

Inbound socket payloads never throw. Bad JSON or a payload that does not match the server-message schema is emitted on the error event instead:

matchSession.on('error', errorPayload => {
  if (errorPayload.code === 'sdk_invalid_server_message') {
    // Transport-level decode failure.
  }
  else {
    // Engine-side error payload.
  }
})

This keeps the socket listener resilient to transient garbage or schema drift without crashing the app.

Transport failures

Network failures from fetch propagate as native TypeError (or similar, depending on the runtime). WebSocket connect failures before the handshake completes reject the matchSession.connect() promise with a generic Error and are recorded in matchSession.errors.