Error Handling

The WalletHero API uses standard HTTP status codes and returns detailed error messages to help you debug issues.

Error Response Format

All errors follow this structure:

{
  "errors": [
    {
      "message": "Human-readable error description",
      "extensions": {
        "code": "ERROR_CODE",
        "field": "field_name"
      }
    }
  ]
}

For WalletHero extension endpoints, errors may use this simplified format:

{
  "error": "Error description",
  "reason": "Detailed reason"
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded with no response body
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource already exists
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Common Error Codes

Authentication Errors

Code	Description
INVALID_CREDENTIALS	Email or password is incorrect
INVALID_TOKEN	The authentication token is invalid
TOKEN_EXPIRED	The session token has expired
EMAIL_NOT_VERIFIED	Email address hasn't been verified

Validation Errors

Code	Description
INVALID_PAYLOAD	Request body is malformed or missing required fields
FAILED_VALIDATION	One or more fields failed validation
RECORD_NOT_UNIQUE	A record with the same unique field already exists

Permission Errors

Code	Description
FORBIDDEN	You don't have permission for this action
WORKSPACE_ACCESS_DENIED	You don't have access to this workspace
INSUFFICIENT_ROLE	Your role doesn't allow this action

Resource Errors

Code	Description
RECORD_NOT_FOUND	The requested resource doesn't exist
SEGMENT_NOT_FOUND	The specified segment doesn't exist

Handling Errors in Code

SDK Error Handling

import { WalletHero, WalletHeroError } from '@wallethero/sdk';

const client = new WalletHero({ apiToken: 'your-token' });

try {
  const template = await client.passTemplates.get('non-existent-id');
} catch (error) {
  if (error instanceof WalletHeroError) {
    console.log('Status:', error.status);    // 404
    console.log('Code:', error.code);        // RECORD_NOT_FOUND
    console.log('Message:', error.message);  // Record not found
  }
}

REST API Error Handling

const response = await fetch('https://api.wallethero.app/items/pass_templates', {
  headers: { 'Authorization': `Bearer ${token}` }
});

if (!response.ok) {
  const error = await response.json();

  switch (response.status) {
    case 401:
      // Refresh token or re-authenticate
      break;
    case 403:
      // Check permissions
      break;
    case 429:
      // Wait and retry
      const retryAfter = response.headers.get('Retry-After');
      break;
    default:
      console.error('API Error:', error.errors?.[0]?.message);
  }
}

Validation Error Details

Validation errors include field-specific information:

{
  "errors": [
    {
      "message": "\"email\" must be a valid email",
      "extensions": {
        "code": "FAILED_VALIDATION",
        "field": "email"
      }
    },
    {
      "message": "\"password\" length must be at least 8 characters",
      "extensions": {
        "code": "FAILED_VALIDATION",
        "field": "password"
      }
    }
  ]
}

Retry Strategy

For transient errors (5xx, 429), implement exponential backoff:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.ok) return response;

    if (response.status >= 500 || response.status === 429) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    throw new Error(`Request failed: ${response.status}`);
  }

  throw new Error('Max retries exceeded');
}