Error Codes

Complete reference for all TIX Protocol error codes and handling strategies.

Error Code Reference

Authorization Errors

Code	Name	Description	Resolution
6000	Unauthorized	Signature or authority mismatch	Verify signer has required authority
6001	NotPermitOwner	Signer is not the permit owner	Use owner's keypair or integrator authority
6002	NotListingSeller	Signer is not the listing seller	Only seller, integrator, or protocol can cancel

Integrator Errors

Code	Name	Description	Resolution
6010	IntegratorSuspended	Integrator is not Active	Contact protocol operator
6011	InvalidIntegrator	Integrator account mismatch	Verify integrator PDA

Event Errors

Code	Name	Description	Resolution
6020	SupplyExceeded	Ticket ID >= total supply	Use valid ticket ID
6021	InvalidEventId	Event ID mismatch	Verify event ID
6022	EventSealed	Event is sealed (reserved)	Cannot modify sealed event

Permit Errors

Code	Name	Description	Resolution
6030	TicketAlreadyMinted	Ticket slot already used	Use different ticket ID
6031	PermitNotActive	Permit is Used or Void	Cannot operate on inactive permits
6032	InvalidPageIndex	Page index doesn't match ticket ID	Use ticket_id / 128
6033	PermitLocked	Permit has active listing lock	Cancel listing first

Listing Errors

Code	Name	Description	Resolution
6040	ListingActive	Listing already exists	Cancel existing listing
6041	ListingNotActive	Listing is not active	Cannot accept inactive listing
6042	ListingExpired	Listing past expiry time	Seller must re-list
6043	ListingVersionMismatch	Permit changed since listing	Re-fetch and create new listing
6044	BuyerNotAllowed	Buyer not on allowlist	Only allowed buyer can purchase

Royalty Errors

Code	Name	Description	Resolution
6050	TooManyRoyaltyRecipients	More than 3 recipients	Reduce to max 3
6051	RoyaltyBpsMismatch	Recipient BPS don't sum	Fix BPS allocation
6052	InvalidRoyaltyDest	Invalid royalty ATA	Verify recipient ATAs

Token Errors

Code	Name	Description	Resolution
6060	InvalidMint	Wrong USDC mint	Use correct USDC mint
6061	InsufficientFunds	Not enough USDC	Fund the account
6062	InvalidDecimals	USDC decimals < 2	Use valid USDC mint

Pre-Validation

Validate before submitting transactions:

async function validateIssuePermit(
  connection: Connection,
  eventId: bigint,
  ticketId: bigint,
  integratorIdentity: PublicKey
) {
  const errors = [];

  // Check integrator status
  const [integratorPubkey] = integratorPda(integratorIdentity);
  const integrator = await getIntegrator(connection, integratorPubkey);

  if (integrator.status !== "Active") {
    errors.push({
      code: "IntegratorSuspended",
      message: "Integrator is not active",
    });
  }

  // Check event capacity
  const [eventPubkey] = eventPda(eventId);
  const event = await getEvent(connection, eventPubkey);

  if (ticketId >= event.totalSupply) {
    errors.push({
      code: "SupplyExceeded",
      message: `Ticket ID ${ticketId} exceeds supply ${event.totalSupply}`,
    });
  }

  // Check if already minted
  try {
    const permit = await getPermit(connection, eventPubkey, ticketId);
    if (permit.version > 0n) {
      errors.push({
        code: "TicketAlreadyMinted",
        message: `Ticket ${ticketId} already issued`,
      });
    }
  } catch {
    // Page doesn't exist yet, which is fine
  }

  // Check treasury balance
  const treasuryBalance = await connection.getTokenAccountBalance(
    integrator.treasuryUsdc
  );
  const config = await getProtocolConfig(connection, protocolConfigPda()[0]);

  if (BigInt(treasuryBalance.value.amount) < config.permitFeeMinor) {
    errors.push({
      code: "InsufficientFunds",
      message: "Integrator treasury has insufficient USDC",
    });
  }

  return {
    valid: errors.length === 0,
    errors,
  };
}

Common Error Scenarios

Scenario: Concurrent Purchases

// Two buyers try to purchase the same listing simultaneously

// Buyer A's transaction succeeds
// Buyer B gets: ListingNotActive or ListingVersionMismatch

async function safePurchase(eventId: bigint, ticketId: bigint) {
  // Always re-fetch listing state before purchase
  const [listingPubkey] = listingPda(eventId, ticketId);
  const listing = await getListing(connection, listingPubkey);

  if (!listing.active) {
    throw new Error("Listing no longer available");
  }

  // Proceed with purchase...
}

Scenario: Stale Listing

// Ticket was transferred after listing was created

// Symptom: ListingVersionMismatch

// Solution: Re-list with current version
async function handleStaleListingError(eventId: bigint, ticketId: bigint) {
  // Fetch current permit state
  const [eventPubkey] = eventPda(eventId);
  const permit = await getPermit(connection, eventPubkey, ticketId);

  // The listing is invalid because permit.version changed
  // Cancel the stale listing
  await cancelListing({
    connection,
    payer: seller.publicKey,
    eventId,
    ticketId,
    authority: seller.publicKey,
  });

  // Create new listing with current version
  // (The SDK will use current permit.version)
}

Scenario: Insufficient Treasury

// Integrator treasury runs out of USDC

// Symptom: InsufficientFunds on issue_permit or transfer_permit

async function ensureTreasuryFunded(minBalance: bigint, fundSource: PublicKey) {
  const balance = await connection.getTokenAccountBalance(treasuryAta);

  if (BigInt(balance.value.amount) < minBalance) {
    // Transfer USDC to treasury
    await transfer(
      connection,
      fundingKeypair,
      fundSource,
      treasuryAta,
      fundingKeypair,
      Number(minBalance - BigInt(balance.value.amount))
    );
  }
}