Error Handling & Resilience

// types/index.ts
export class ApiError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly code: string,
    message: string,
    public readonly details?: Record<string, unknown>,
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

# exceptions.py
class SentServiceException(Exception):
    def __init__(self, message: str, status_code: int = 500):
        self.message = message
        self.status_code = status_code
        super().__init__(self.message)

// internal/models — a single HTTP-shaped error the edge can render.
type HTTPError struct {
    Code      int    `json:"-"`
    ErrorCode string `json:"code"`
    Message   string `json:"message"`
}

var ErrMissingAPIKey = &HTTPError{
    Code:      http.StatusUnauthorized,
    ErrorCode: "UNAUTHORIZED",
    Message:   "Missing API key — send it as Authorization: Bearer <key>.",
}

// services/sent.service.ts — translate the SDK error, don't leak it.
import { APIError as SentApiError } from '@sentdm/sentdm';

private toApiError(error: unknown, fallbackMessage: string): ApiError {
  this.logger.error({ error }, fallbackMessage);
  if (error instanceof SentApiError) {
    const e = error as { status?: number; name: string; message: string; headers?: unknown };
    // e.name is BadRequestError | AuthenticationError | RateLimitError | …
    return new ApiError(e.status || 500, e.name, e.message, {
      headers: e.headers as Record<string, unknown> | undefined,
    });
  }
  return new ApiError(500, 'InternalError', fallbackMessage);
}

# exceptions.py — one handler maps every SDK APIError to your envelope.
from sent_dm import APIError

async def sent_api_exception_handler(request: Request, exc: APIError) -> JSONResponse:
    # The Python SDK exposes `status_code` (not `status`); the class name is the label.
    status_code = {400: 400, 401: 401, 403: 403, 404: 404, 422: 422, 429: 429}.get(
        getattr(exc, "status_code", 500), 500
    )
    return JSONResponse(
        status_code=status_code,
        content={
            "error": type(exc).__name__,
            "message": str(exc),
            "status_code": status_code,
        },
    )

# For per-call handling, catch the typed subclasses:
#   from sent_dm import BadRequestError, AuthenticationError, RateLimitError, APIError

// The SDK returns a typed *sentdm.Error; unwrap it to read StatusCode.
result, err := client.Messages.Send(ctx, params)
if err != nil {
    var apiErr *sentdm.Error
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case http.StatusTooManyRequests:
            return &models.HTTPError{Code: 429, ErrorCode: "RATE_LIMITED", Message: apiErr.Error()}
        case http.StatusUnauthorized:
            return &models.HTTPError{Code: 401, ErrorCode: "UNAUTHORIZED", Message: apiErr.Error()}
        }
    }
    return fmt.Errorf("failed to send message: %w", err)
}

// exception/GlobalExceptionHandler.java — @RestControllerAdvice maps each type.
@ExceptionHandler(UnauthorizedException.class)
public ResponseEntity<ProblemDetail> handleUnauthorized(UnauthorizedException ex, HttpServletRequest req) {
    ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.UNAUTHORIZED);
    problem.setTitle("Unauthorized");
    problem.setDetail(ex.getMessage());
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(problem);
}

@ExceptionHandler(Exception.class) // catch-all → RFC 7807 ProblemDetail
public ResponseEntity<ProblemDetail> handleGeneric(Exception ex, HttpServletRequest req) {
    ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
    problem.setTitle("Internal Server Error");
    problem.setDetail(ex.getMessage());
    return ResponseEntity.internalServerError().body(problem);
}

// Middleware/GlobalExceptionMiddleware.cs — map SentApiException → status.
private static (int Status, string Title, string Detail) MapSdkException(SentApiException ex)
{
    var status = ex.StatusCode switch
    {
        HttpStatusCode.Unauthorized       => StatusCodes.Status401Unauthorized,
        HttpStatusCode.NotFound           => StatusCodes.Status404NotFound,
        HttpStatusCode.Conflict           => StatusCodes.Status409Conflict,
        HttpStatusCode.UnprocessableEntity=> StatusCodes.Status422UnprocessableEntity,
        HttpStatusCode.TooManyRequests    => StatusCodes.Status429TooManyRequests,
        _                                 => StatusCodes.Status502BadGateway,
    };
    return (status, "Sent DM API Error", ex.Message);
}

// app/Services/SentDM/SentDMService.php — catch the SDK's APIException.
use SentDm\Core\Exceptions\APIException;

try {
    $response = $this->client->messages->send(/* … */);
    // … map response …
} catch (APIException $e) {
    Log::error('Failed to send message', ['error' => $e->getMessage()]);
    return new MessageResult(success: false, error: $e->getMessage());
}

# app/services/sent_dm/base_service.rb — one place translates SDK errors.
def handle_api_error(error)
  Rails.logger.error "[SentDM] API Error: #{error.class} - #{error.message}"
  failure(:api_error, error.message)
end

# In a service:
#   rescue ApplicationService::ValidationError => e
#     failure(:validation_error, e.message)
#   rescue StandardError => e
#     handle_api_error(e)

// lib/sent/client.ts
export function clientForApiKey(apiKey: string): SentDm {
  return new SentDm({
    apiKey,
    maxRetries: 2,
    timeout: 30 * 1000,
  });
}

// SentClientFactory.php — maxRetries is set via requestOptions (default 2).
return new Client(
    apiKey: $apiKey,
    requestOptions: ['maxRetries' => $this->maxRetries],
);

// Per-call deadline; the SDK handles retry of transient failures internally.
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
response, err := c.client.Messages.Send(ctx, params)