Error handling

import {
  MatterError,
  MatterValidationError,
  MatterAuthorizationError,
  MatterIdempotencyReplayError,
  MatterRateLimitError,
  MatterUpstreamUnavailableError,
} from "@mattermode/node";

try {
  await matter.entities.create({ jurisdiction: "US-DE" });
} catch (err) {
  if (err instanceof MatterValidationError) {
    // 400 — surface field-level errors to the caller
    return { ok: false, fields: err.errors };
  }
  if (err instanceof MatterAuthorizationError) {
    // 403 — token tier or scope is wrong
    log.warn("scope insufficient", { code: err.code });
    throw err;
  }
  if (err instanceof MatterIdempotencyReplayError) {
    // 409 — same key with a different body. Bug in the caller.
    log.error("idempotency replay", { key: err.idempotencyKey });
    throw err;
  }
  if (err instanceof MatterRateLimitError) {
    // 429 — SDK already retried; we've exhausted maxRetries
    log.warn("rate limited", { retryAfter: err.retryAfter });
    throw err;
  }
  if (err instanceof MatterUpstreamUnavailableError) {
    // 503 — Secretary of State portal down. Already retried.
    log.error("upstream down", { upstream: err.upstream });
    throw err;
  }
  if (err instanceof MatterError) {
    log.error("matter error", { type: err.type, requestId: err.requestId });
    throw err;
  }
  throw err; // network, parse, or unknown
}

from matter.errors import (
    MatterError,
    MatterValidationError,
    MatterAuthorizationError,
    MatterIdempotencyReplayError,
    MatterRateLimitError,
    MatterUpstreamUnavailableError,
)

try:
    matter.entities.create(jurisdiction="US-DE")
except MatterValidationError as err:
    # 400 — surface field-level errors to the caller
    return {"ok": False, "fields": err.errors}
except MatterAuthorizationError as err:
    # 403 — token tier or scope is wrong
    log.warning("scope insufficient", extra={"code": err.code})
    raise
except MatterIdempotencyReplayError as err:
    # 409 — same key with a different body. Bug in the caller.
    log.error("idempotency replay", extra={"key": err.idempotency_key})
    raise
except MatterRateLimitError as err:
    # 429 — SDK already retried; we've exhausted max_retries
    log.warning("rate limited", extra={"retry_after": err.retry_after})
    raise
except MatterUpstreamUnavailableError as err:
    # 503 — Secretary of State portal down. Already retried.
    log.error("upstream down", extra={"upstream": err.upstream})
    raise
except MatterError as err:
    log.error("matter error", extra={"type": err.type, "request_id": err.request_id})
    raise

import (
    "errors"

    "github.com/matterhq/matter-go"
)

_, err := client.Entities.Create(ctx, &matter.EntityCreateParams{Jurisdiction: "US-DE"})
if err != nil {
    var verr *matter.ValidationError
    var aerr *matter.AuthorizationError
    var ierr *matter.IdempotencyReplayError
    var rerr *matter.RateLimitError
    var uerr *matter.UpstreamUnavailableError
    var merr *matter.Error

    switch {
    case errors.As(err, &verr):
        // 400 — surface field-level errors to the caller
        return Result{Ok: false, Fields: verr.Errors}, nil
    case errors.As(err, &aerr):
        log.Warn("scope insufficient", "code", aerr.Code)
        return Result{}, err
    case errors.As(err, &ierr):
        log.Error("idempotency replay", "key", ierr.IdempotencyKey)
        return Result{}, err
    case errors.As(err, &rerr):
        log.Warn("rate limited", "retry_after", rerr.RetryAfter)
        return Result{}, err
    case errors.As(err, &uerr):
        log.Error("upstream down", "upstream", uerr.Upstream)
        return Result{}, err
    case errors.As(err, &merr):
        log.Error("matter error", "type", merr.Type, "request_id", merr.RequestID)
        return Result{}, err
    default:
        return Result{}, err // network, ctx cancellation, etc.
    }
}

catch (err) {
  if (err instanceof MatterValidationError) {
    for (const e of err.errors) {
      console.log(`${e.path}: ${e.code} — ${e.message}`);
    }
  }
}

except MatterValidationError as err:
    for e in err.errors:
        print(f"{e.path}: {e.code} — {e.message}")

var verr *matter.ValidationError
if errors.As(err, &verr) {
    for _, e := range verr.Errors {
        fmt.Printf("%s: %s — %s\n", e.Path, e.Code, e.Message)
    }
}