Failures are typed, bounded, and safe to correlate.

Handle behavior from code and retryable. Show users a calm product message. Log the request ID—not the credential, Authorization header, response body, or private application state.

Error envelope

HTTP/1.1 429 Too Many Requests
Cache-Control: private, no-store
Content-Type: application/json
Retry-After: 17
X-Request-Id: errors-rate-001

{
  "schema": "casset.error.v1",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Try again after the retry window.",
    "requestId": "errors-rate-001",
    "retryable": true
  }
}

Complete error reference

Parser error

CassetContractError is not an HTTP error code. Direct calls toparsePublicArtistResponse, parsePublicCatalogResponse, or parseHeadlessApiErrorEnvelope throw it when a value violates the exact schema. Its issues array contains only field paths and bounded validation messages. When the HTTP client encounters the same problem, it throws a non-retryable IntegrationFailure instead.

Handle errors in TypeScript

import {
  CassetApiError,
  InvalidCredential,
  InvalidRequest,
  RateLimited,
  ResourceUnavailable,
} from "@casset/apps"

try {
  const catalog = await casset.getCatalog("connor")
  return catalog.tracks
} catch (error) {
  if (error instanceof InvalidRequest) {
    throw new Error("Invalid integration input")
  }

  if (error instanceof InvalidCredential) {
    return { state: "reauthorize-local-sandbox" }
  }

  if (error instanceof ResourceUnavailable && error.status === 404) {
    return { state: "artist-unavailable" }
  }

  if (error instanceof RateLimited) {
    return { state: "try-later", requestId: error.requestId }
  }

  if (error instanceof CassetApiError) {
    console.info("Casset request failed", {
      code: error.code,
      status: error.status,
      retryable: error.retryable,
      requestId: error.requestId,
    })
    return { state: "temporarily-unavailable" }
  }

  throw error
}

Request IDs and correlation

Casset uses one correlation value: x-request-id. There is no separate public correlation-ID header. If you send a valid ID, the server mirrors it in the response header and error body. Otherwise, the server generates a req_* value. The SDK generates one sdk-*value and reuses it across all retry attempts.

• Accepted length: 8–120 characters.
• Accepted characters: letters, digits, period, underscore, colon, and hyphen.
• Secret-like prefixes, JWT-shaped values, control characters, and whitespace are rejected.
• A response header/body mismatch or a response ID that differs from the request becomes a non-retryable integration failure.

Debugging workflow

1. Capture code, status, retryable, and requestId.
2. Confirm whether the request targeted public v1, the local sandbox, or an exact mock.
3. For 400/401/403/404, fix state or render the appropriate terminal fallback; do not loop.
4. For 429 or retryable 5xx, let the SDK finish its bounded attempts before adding application-level recovery.
5. For non-retryable IntegrationFailure, compare the exact response schema and request-ID header. Treat drift as an integration defect.
6. Share the request ID and sanitized metadata with the Casset maintainer. Never share the Bearer value or webhook signing secret.

See Retries for exact attempt and delay behavior, or Observability for the full safe-logging boundary.