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 the
// SDK's exported types (dm.sent.errors.*) to RFC 7807 ProblemDetail.
import dm.sent.errors.RateLimitException;
import dm.sent.errors.SentException;

@ExceptionHandler(RateLimitException.class) // SDK 429 — act on it differently
public ResponseEntity<ProblemDetail> handleRateLimit(RateLimitException ex) {
    ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.TOO_MANY_REQUESTS);
    problem.setTitle("Rate Limited");
    problem.setDetail(ex.getMessage());
    return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS).body(problem);
}

@ExceptionHandler(SentException.class) // fall through to the SDK base type
public ResponseEntity<ProblemDetail> handleSentException(SentException ex) {
    ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_GATEWAY);
    problem.setTitle("Messaging Provider Error");
    problem.setDetail(ex.getMessage());
    return ResponseEntity.status(HttpStatus.BAD_GATEWAY).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 typed exceptions,
// rethrow your one internal error type; the edge handler renders it as JSON.
use SentDm\Core\Exceptions\APIException;
use SentDm\Core\Exceptions\BadRequestException;
use SentDm\Core\Exceptions\RateLimitException;

try {
    $response = $this->client->messages->send(/* … */);
    // … map response …
} catch (RateLimitException $e) {
    throw new ApiError(429, 'RATE_LIMITED', $e->getMessage());    // SDK 429
} catch (BadRequestException $e) {
    throw new ApiError(400, 'INVALID_REQUEST', $e->getMessage()); // SDK 400
} catch (APIException $e) {
    Log::error('Sent API call failed', ['error' => $e->getMessage()]);
    throw new ApiError(502, 'UPSTREAM_ERROR', $e->getMessage());  // SDK base
}

# app/services/sent_dm/base_service.rb — rescue the SDK's typed errors
# (Sentdm::Errors::*), rethrow your one internal error type.
def send_message(params)
  # … client.messages.send(**params) …
rescue Sentdm::Errors::RateLimitError => e
  raise ApiError.new(status: 429, code: "RATE_LIMITED", message: e.message)
rescue Sentdm::Errors::BadRequestError => e
  raise ApiError.new(status: 400, code: "INVALID_REQUEST", message: e.message)
rescue Sentdm::Errors::APIError => e # fall through to the SDK base type
  Rails.logger.error "[SentDM] #{e.class}: #{e.message}"
  raise ApiError.new(status: 502, code: "UPSTREAM_ERROR", message: e.message)
end

# One edge handler renders it: `rescue_from ApiError` in ApplicationController.

// 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)