Errors

Every domain failure in the Highlight backend raises a named error with a stable name (the class name) and a typed payload. Route handlers map each error class to an HTTP status code — your client can either switch on the status code or pattern-match against the error payload shape.

Error response shape

Typed domain errors come back as JSON:

{
  "name": "CollectionNotFoundError",
  "message": "Collection 0x...abc not found",
  "data": { "highlightId": "0x...abc" }
}

name — the class name. Unique across the platform; safe to switch on.
message — human-readable; safe to log, not safe to parse.
data — structured payload (e.g. highlightId, chainId).

Untyped runtime failures (unhandled exceptions, 5xx from upstream services) come back as a generic 500 with a more minimal shape.

Collection errors

Error	Status	When
`CollectionNotFoundError`	404	`highlightId` doesn’t exist
`CollectionNotPublicError`	404	Collection exists but is `Draft` and caller isn’t the owner
`CollectionNotOwnedError`	403	Caller authenticated but not the collection owner
`CollectionNotDraftError`	400	Attempting a draft-only operation on a live collection
`CollectionContractNotFoundError`	404	Referenced `contractId` doesn’t exist
`CollectionContractNotOwnedError`	403	Caller doesn’t own the referenced contract
`InvalidCollectionInputError`	400	Schema-level validation failure (e.g. missing logo)
`InvalidTypeSpecificDetailsError`	400	Edition/series/generative details don’t match the collection type
`CollectionMediaNotFoundError`	404	Referenced `mediaId` doesn’t exist
`CollectionMediaNotOwnedError`	403	Caller doesn’t own the referenced media
`CollectionMediaUploadNotReadyError`	400	Media isn’t `Ready` yet — wait for processing
`CollectionMediaInvalidPurposeError`	400	Media kind doesn’t fit the slot (e.g. Directory as logo)
`CollectionMediaNotOnchainReadyError`	400	Media not published to archive provider yet
`BaseUriNotSetError`	400	Cannot finalize metadata before base URI is computed

Sale errors

Error	Status	When
`SaleNotFoundError`	404	`saleId` doesn’t exist or isn’t on this collection
`SaleNotPublicError`	403	Attempting to act on a gated sale without gate pass
`SaleNotLiveError`	400	Claim/bid against a non-live sale
`SaleAlreadyExistsError`	409	Draft collections allow one sale at a time
`SaleCannotDeleteLiveError`	400	Live sales cannot be deleted — pause or end-date
`SaleTypeNotSupportedError`	400	Combination not in the support matrix
`InvalidSalePriceError`	400	Price is zero, negative, or malformed
`InvalidTypeConfigError`	400	`typeConfig` fails schema validation for the sale type
`ChooseTokenNotSupportedError`	400	`tokenIds` passed for a non-series or non-fixed/dutch sale
`AuctionNotEndedError`	400	Cannot claim a ranked-auction sale before `endAt`
`NoValidBidsError`	400	Claiming a ranked auction but the caller has no valid winning bids
`VectorIdRequiredError`	400	Public Dutch auction claim needs a registered vectorId
`SaleGateCheckFailedError`	403	Caller’s wallet doesn’t satisfy the gate conditions
`AccountContextRequiredError`	401	Claim/bid without auth
`AccountWalletRequiredError`	400	Account has no wallet configured
`ContractAddressRequiredError`	400	Gated claim against an undeployed contract
`SaleMechanicNotFoundError`	400	Referenced `mechanicId` doesn’t exist
`SaleMechanicDeploymentNotFoundError`	400	Mechanic has no deployment on this chain

Gate errors

Error	Status	When
`GateNotFoundError`	404	`gateId` doesn’t exist
`GateNotOwnedError`	403	Caller doesn’t own the gate
`ConditionTypeNotSupportedError`	400	Unknown `type` in a condition config

Media errors

Error	Status	When
`MediaNotFoundError`	404	`mediaId` doesn’t exist
`MediaNotOwnedError`	403	Caller doesn’t own the media
`MediaUploadNotFoundError`	404	No upload session on this media
`MediaTooLargeError`	400	`fileSize` exceeds per-kind limit
`MediaKindMismatchError`	400	Uploading bytes of the wrong MIME for the declared kind
`MediaInUseError`	409	Deleting media referenced by a deployed contract
`MediaStorageUnavailableError`	502	Upstream storage provider rejected the write
`DirectoryNotFinalizedError`	400	Using a Directory before extraction is `Ready`
`LocationNotFoundError`	404	No storage location record for this media
`ProviderUploadFailedError`	502	Upload to R2/Arweave failed; safe to retry

Zip extraction errors

Error	Status	When
`ExtractionNotFoundError`	404	No extraction record for this media
`ExtractionAlreadyExistsError`	409	Extraction already running
`ExtractionNotRetryableError`	400	Extraction is in a state that can’t be retried
`ExtractionMediaNotZipError`	400	Media kind isn’t Directory
`ExtractionMediaNotUploadedError`	400	Bytes never PUT to the upload URL
`ExtractionMediaNotFoundError`	404	Parent media record missing

SIWE errors

Error	Status	When
`SiweInvalidMessageError`	400	Message isn’t valid EIP-4361
`SiweDomainMismatchError`	400	Message `domain` doesn’t match the backend’s expected host
`SiweChainNotAllowedError`	400	`chainId` in the message isn’t on the allow-list
`SiweNonceInvalidError`	400	Nonce is expired, unknown, or reused
`SiweInvalidSignatureError`	400	Signature doesn’t recover to the message’s `address`

User / API key errors

Error	Status	When
`ProviderVerificationFailedError`	400	Privy token rejected
`InsufficientCredentialsError`	400	Sign-in request missing required fields
`ApiKeyNotFoundError`	404	`apiKeyId` doesn’t exist
`ApiKeyNotOwnedError`	403	Caller doesn’t own the key
`ApiKeyRevokedError`	401	Key was revoked
`ApiKeyExpiredError`	401	Key’s `expiresAt` has passed
`InvalidApiKeyError`	401	Key doesn’t match any record

Deployment errors

Error	Status	When
`DeploymentNotFoundError`	404	No deployment for this collection
`DeploymentAlreadyExistsError`	409	Deploy already initiated; poll status instead

Shared infrastructure errors

These map to 500 because they indicate misconfiguration or upstream failure, not client error.

Error	Status	When
`SystemContractNotFoundError`	500	No system-contract record for chain + type
`RpcUrlNotConfiguredError`	500	Chain has no RPC URL in config
`EncryptionKeyNotConfiguredError`	500	KMS key missing
`ExecutorKeyNotConfiguredError`	500	Platform executor key missing for this chain
`ExecutorKeyDecryptionFailedError`	500	KMS decrypt failed
`SigningKeyNotConfiguredError`	500	Sale-signing key missing
`SiweConfigNotConfiguredError`	500	SIWE domain/allow-list missing

Shared validation errors

Error	Status	When
`ChainNotFoundError`	400	`chainId` isn’t supported
`CurrencyNotSupportedError`	400	`currency` not configured on this chain

Handling errors in the SDK

The generated SDK returns a discriminated { data, error, response } shape — no exceptions on non-2xx. Example:

const res = await client.collection.get({ highlightId });

if (res.error) {
  if (res.response?.status === 404) {
    // CollectionNotFoundError or CollectionNotPublicError
    return null;
  }
  if (res.response?.status === 403) {
    // CollectionNotOwnedError
    throw new Error("Not authorized to view this collection");
  }
  throw res.error;
}

return res.data;

For finer-grained dispatch, inspect res.error.name:

if (res.error && typeof res.error === "object" && "name" in res.error) {
  switch (res.error.name) {
    case "CollectionNotFoundError":
    case "CollectionNotPublicError":
      return null;
    case "CollectionNotOwnedError":
      throw new Error("Forbidden");
    default:
      throw res.error;
  }
}

Support matrix — What combinations are valid (most 400s come from invalid combinations).
Authentication — Causes of 401s and 403s.