Error Handling - Ticketnation

Error Response Format

All errors follow a consistent format with an optional hint field that provides actionable guidance:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Event not found: abc-123",
    "hint": "Check that the event ID is correct and belongs to your organization.",
    "details": []
  },
  "requestId": "req_a1b2c3d4e5f6"
}

The requestId is unique per request — include it in support tickets for faster debugging.

Error Codes

Code	HTTP Status	Description	Common Cause
`VALIDATION_ERROR`	400	Input failed validation	Missing required fields, invalid format
`UNAUTHORIZED`	401	Authentication failed	Missing/invalid/expired API key
`FORBIDDEN`	403	Not allowed	Missing scope, IP not in allowlist
`SCOPE_REQUIRED`	403	Specific scope needed	Key lacks the required scope
`NOT_FOUND`	404	Resource not found	Wrong ID, or resource belongs to another org
`RATE_LIMITED`	429	Too many requests	Exceeded rate limit for your tier
`INTERNAL_ERROR`	500	Server error	Transient failure — retry with backoff

The Hint System

Error responses include a hint field with a human-readable suggestion for how to resolve the issue. Hints are tailored to the specific error context.

VALIDATION_ERROR hints

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "hint": "The 'dateTime' field must be a valid ISO 8601 date string (e.g., '2025-06-15T18:00:00.000Z').",
    "details": [
      { "field": "name", "message": "name should not be empty" },
      { "field": "dateTime", "message": "dateTime must be a valid ISO 8601 date string" }
    ]
  },
  "requestId": "req_x1y2z3"
}

SCOPE_REQUIRED hints

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "This endpoint requires the 'events:write' scope.",
    "hint": "Update your API key's scopes in the Organizer Dashboard under Settings > API Keys, or create a new key with 'events:write' enabled."
  },
  "requestId": "req_a1b2c3"
}

NOT_FOUND hints

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Event not found: abc-123",
    "hint": "Check that the event ID is correct and belongs to your organization. Use tn.events.list() to see your events."
  },
  "requestId": "req_d4e5f6"
}

RATE_LIMITED hints

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "hint": "You have exceeded 60 requests per minute. Wait until the X-RateLimit-Reset timestamp before retrying. Consider upgrading to a higher tier for increased limits."
  },
  "requestId": "req_g7h8i9"
}

Validation Errors

When the code is VALIDATION_ERROR, the details array contains field-level information:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "hint": "Fix the fields listed in 'details' and retry your request.",
    "details": [
      { "field": "name", "message": "name should not be empty" },
      { "field": "dateTime", "message": "dateTime must be a valid ISO 8601 date string" }
    ]
  },
  "requestId": "req_x1y2z3"
}

SDK Error Handling

The SDK throws typed TicketnationError instances with all fields including hint:

import { TicketnationError } from 'ticketnation-sdk';

try {
  await tn.events.create({ name: '' });
} catch (error) {
  if (error instanceof TicketnationError) {
    console.log(`Code: ${error.code}`);         // 'VALIDATION_ERROR'
    console.log(`Status: ${error.status}`);     // 400
    console.log(`Message: ${error.message}`);   // 'Validation failed'
    console.log(`Hint: ${error.hint}`);         // 'Fix the fields listed in...'
    console.log(`Request ID: ${error.requestId}`);
    console.log(`Details:`, error.details);     // [{ field: 'name', message: '...' }]
  }
}

Complete Error Handler Example

import { TicketnationError } from 'ticketnation-sdk';

async function safeCreateEvent(params: CreateEventParams) {
  try {
    return await tn.events.createAndPublish(params);
  } catch (error) {
    if (!(error instanceof TicketnationError)) {
      throw error; // Not a Ticketnation error
    }

    switch (error.code) {
      case 'VALIDATION_ERROR':
        console.error('Fix these fields:', error.details);
        if (error.hint) console.error('Hint:', error.hint);
        break;

      case 'UNAUTHORIZED':
        console.error('Check your API key');
        if (error.hint) console.error('Hint:', error.hint);
        break;

      case 'SCOPE_REQUIRED':
        console.error('Missing scope:', error.message);
        if (error.hint) console.error('Hint:', error.hint);
        break;

      case 'RATE_LIMITED':
        console.error('Slow down — retry after a pause');
        if (error.hint) console.error('Hint:', error.hint);
        break;

      case 'NOT_FOUND':
        console.error('Resource not found:', error.message);
        if (error.hint) console.error('Hint:', error.hint);
        break;

      case 'TIMEOUT':
        console.error('Request timed out — retry');
        break;

      case 'NETWORK_ERROR':
        console.error('Check your internet connection');
        break;

      default:
        console.error(`${error.code}: ${error.message}`);
        if (error.hint) console.error('Hint:', error.hint);
    }

    return null;
  }
}

TicketnationError Properties

Property	Type	Description
`code`	string	Error code (e.g., `VALIDATION_ERROR`, `NOT_FOUND`)
`status`	number	HTTP status code (0 for client-side errors like TIMEOUT)
`message`	string	Human-readable error message
`requestId`	string	Unique request identifier for support
`details`	array	Field-level errors (for `VALIDATION_ERROR`)
`hint`	string	Actionable suggestion for resolving the error

SDK-Only Error Codes

These codes are generated by the SDK itself, not the API:

Code	Status	Description	Fix
`TIMEOUT`	0	Request exceeded the configured timeout	Increase `timeout` in config, or check network
`NETWORK_ERROR`	0	DNS/connection failure	Verify `baseUrl` is reachable
`HTTP_ERROR`	varies	Server returned error with no parseable body	Transient — retry

Automatic Retries

The SDK automatically retries on 5xx server errors with exponential backoff:

Attempt 1: immediate
Attempt 2: after 1 second
Attempt 3: after 2 seconds

Not retried: 4xx errors (400, 401, 403, 404, 429) — these are client errors that need to be fixed. Configure retries:

const tn = new Ticketnation({
  apiKey: '...',
  retries: 3,   // max retry attempts (default: 2)
});

Rate Limit Headers

Every response includes rate limit information:

Header	Description
`X-RateLimit-Limit`	Max requests for your tier
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you hit the limit, the response is 429 with a RATE_LIMITED error. Wait until X-RateLimit-Reset before retrying.

Troubleshooting

UNAUTHORIZED on every request

Verify your API key is correct and not expired
Check the api-key header name (not Authorization)
Ensure the key has not been deleted from the dashboard

SCOPE_REQUIRED when calling an endpoint

Check which scope the endpoint needs (see API Reference)
Performers, schedules, and brands require events:write
Update your API key’s scopes in the dashboard, or create a new key with the required scopes
Check the error.hint for specific guidance

NOT_FOUND for a resource you created

Events/tickets are scoped to your organization — you can only access resources owned by the org associated with your API key
Double-check the UUID format
Use tn.events.list() to list your events and verify the ID

Requests timing out

Default timeout is 30 seconds — increase it if needed
Check if baseUrl is correct (no trailing slash)
For local development, use http://localhost:4000

Performers, schedules, or brands returning 403

These resources require the events:write scope
Create a new API key with events:write enabled if your current key does not have it

​Error Response Format

​Error Codes

​The Hint System

​Validation Errors

​SDK Error Handling

​Complete Error Handler Example

​TicketnationError Properties

​SDK-Only Error Codes

​Automatic Retries

​Rate Limit Headers

​Troubleshooting