Error Handling

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key provided"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "fields": [
        {
          "field": "email",
          "message": "Must be a valid email address"
        },
        {
          "field": "to",
          "message": "Phone number must be in E.164 format"
        }
      ]
    }
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 60 seconds",
    "details": {
      "retryAfter": 60
    }
  }
}

import { Transactional, TransactionalError } from 'transactional-sdk';
 
const client = new Transactional({ apiKey: 'your-api-key' });
 
try {
  const email = await client.emails.send({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Hello',
    html: '<p>World</p>',
  });
} catch (error) {
  if (error instanceof TransactionalError) {
    console.error(`Error code: ${error.code}`);
    console.error(`Message: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
 
    // Handle specific errors
    switch (error.code) {
      case 'RATE_LIMITED':
        const retryAfter = error.details?.retryAfter || 60;
        console.log(`Retry after ${retryAfter} seconds`);
        break;
      case 'VALIDATION_ERROR':
        console.log('Validation errors:', error.details?.fields);
        break;
      case 'UNAUTHORIZED':
        console.log('Check your API key');
        break;
    }
  }
}

from transactional import Transactional
from transactional.errors import (
    TransactionalError,
    AuthenticationError,
    ValidationError,
    RateLimitError,
    NotFoundError,
)
 
client = Transactional(api_key="your-api-key")
 
try:
    email = client.emails.send(
        from_email="sender@example.com",
        to="recipient@example.com",
        subject="Hello",
        html="<p>World</p>",
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    for field in e.details.get("fields", []):
        print(f"  - {field['field']}: {field['message']}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NotFoundError as e:
    print(f"Resource not found: {e.message}")
except TransactionalError as e:
    print(f"API error ({e.code}): {e.message}")

// Good
if (error.code === 'RATE_LIMITED') {
  await sleep(error.details.retryAfter * 1000);
  return retry();
}
 
// Bad - messages may change
if (error.message.includes('rate limit')) {
  // This is fragile
}

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (
        error instanceof TransactionalError &&
        error.code === 'RATE_LIMITED' &&
        attempt < maxRetries - 1
      ) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

catch (error) {
  if (error instanceof TransactionalError) {
    console.error({
      timestamp: new Date().toISOString(),
      code: error.code,
      message: error.message,
      statusCode: error.statusCode,
      details: error.details,
      requestId: error.requestId,
    });
  }
}

catch (error) {
  if (error instanceof TransactionalError && error.code === 'VALIDATION_ERROR') {
    const fieldErrors = error.details?.fields || [];
 
    // Map to form errors
    const formErrors = fieldErrors.reduce((acc, err) => {
      acc[err.field] = err.message;
      return acc;
    }, {});
 
    setFormErrors(formErrors);
  }
}

curl -i https://api.usetransactional.com/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Response headers include:
# X-Request-Id: req_abc123xyz