Error Handling

Learn how to handle errors when working with Sesamy APIs.

Error Response Format

All API errors follow a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {
      "field": "field_name",
      "reason": "specific_reason"
    },
    "request_id": "req_abc123"
  }
}

Error Codes

Client Errors (4xx)

Code	HTTP Status	Description
validation_error	400	Invalid request parameters
authentication_required	401	Missing or invalid authentication
insufficient_permissions	403	Insufficient permissions
resource_not_found	404	Resource doesn't exist
rate_limit_exceeded	429	Too many requests

Server Errors (5xx)

Code	HTTP Status	Description
internal_error	500	Internal server error
service_unavailable	503	Service temporarily unavailable

Handling Errors

JavaScript/TypeScript

import { SesamyError, ValidationError, AuthenticationError } from '@sesamy/client';

try {
  const profile = await client.getProfile();
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Redirect to login
    redirectToLogin();
  } else if (error instanceof ValidationError) {
    // Show validation errors
    console.error('Validation failed:', error.details);
  } else if (error instanceof SesamyError) {
    // Handle other API errors
    console.error('API error:', error.code, error.message);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}

Python

from sesamy import SesamyError, ValidationError, AuthenticationError

try:
    profile = client.get_profile()
except AuthenticationError:
    # Redirect to login
    redirect_to_login()
except ValidationError as e:
    # Show validation errors
    print(f'Validation failed: {e.details}')
except SesamyError as e:
    # Handle other API errors
    print(f'API error: {e.code} {e.message}')
except Exception as e:
    # Handle unexpected errors
    print(f'Unexpected error: {e}')

Retry Logic

Implement exponential backoff for transient errors:

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (shouldRetry(error) && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await sleep(delay);
      } else {
        throw error;
      }
    }
  }
}

function shouldRetry(error: any): boolean {
  return (
    error.statusCode >= 500 ||
    error.statusCode === 429 ||
    error.code === 'network_error'
  );
}

Best Practices

1. Check Error Types: Use specific error classes for different scenarios
2. Log Request IDs: Include request IDs in logs for debugging
3. Implement Retries: Retry transient errors with exponential backoff
4. Validate Before Sending: Validate data client-side to reduce errors
5. Monitor Error Rates: Track error rates to identify issues early

Getting Help

Include the request_id when contacting support:

catch (error) {
  console.error(`Request ${error.requestId} failed: ${error.message}`);
  // Contact support with request ID
}