Error Handling

Relevant source files

The following files were used as context for generating this wiki page:

• errors.go
• resend_test.go
• topics.go
• examples/templates.go
• examples/send_email.go

The resend-go library implements a structured error handling system to manage request validation, API communication failures, and rate limiting. It provides specific error types and sentinel values to allow developers to distinguish between client-side validation errors and server-side responses.

Sources: errors.go:1-50, resend_test.go:73-160

Error Architecture

The library categorizes errors into three primary groups:

1. Validation Errors: Triggered when required fields are missing before a request is sent.
2. Service Creation Errors: Sentinel errors returned when the SDK fails to construct a specific API request.
3. API Response Errors: Errors generated from HTTP response codes, including specialized handling for rate limits.

Request Flow and Error Handling

The following diagram illustrates how the library processes a request and handles potential errors at different stages.

Specialized Error Types

RateLimitError

When the Resend API returns a 429 Too Many Requests status, the library parses metadata from the response headers into a RateLimitError struct. This allows you to inspect specific limits and wait times.

Field	Type	Description
Message	string	The error message returned by the API
Limit	string	Maximum requests allowed in the current window
Remaining	string	Requests remaining in the current window
Reset	string	Seconds until the rate limit resets
RetryAfter	string	Recommended wait time in seconds before retrying

Sources: errors.go:20-35, resend_test.go:77-94

MissingRequiredFieldsError

This error occurs locally within the SDK when you attempt to perform an operation without providing mandatory data.
Sources: errors.go:9-15

Service-Specific Errors

The library defines a comprehensive list of sentinel errors for various services. These are returned if the internal NewRequest call fails for a specific service method.

Service	Example Sentinel Errors
Emails	ErrFailedToCreateEmailsSendRequest, ErrFailedToCreateEmailsGetRequest
Templates	ErrFailedToCreateTemplateCreateRequest, ErrFailedToCreateTemplateListRequest
Topics	ErrFailedToCreateTopicCreateRequest, ErrFailedToCreateTopicUpdateRequest
API Keys	ErrFailedToCreateApiKeysCreateRequest, ErrFailedToCreateApiKeysRemoveRequest

Sources: errors.go:50-100, topics.go:68-71

API Error Parsing Logic

The handleError function processes non-success HTTP responses. It attempts to decode the JSON body to find an error message. If the body is not JSON or is missing a message field, it defaults to using the HTTP status text.

// Example logic derived from test cases
func handleError(resp *http.Response) error {
    // If 429, return RateLimitError
    // If 4xx or 5xx, parse {"message": "..."}
    // If no JSON message, return "[ERROR]: HTTP Status Text"
}

Sources: resend_test.go:95-160

Implementation Example

Developers use standard Go error checking to handle these failures. For rate limits, the errors.Is function identifies the specific failure type.

sent, err := client.Emails.Send(params)
if err != nil {
    if errors.Is(err, resend.ErrRateLimit) {
        var rateErr *resend.RateLimitError
        if errors.As(err, &rateErr) {
            fmt.Printf("Retry after %s seconds", rateErr.RetryAfter)
        }
    } else {
        panic(err)
    }
}

Sources: resend_test.go:174-200, examples/send_email.go:31-34

Summary

The resend-go error handling system ensures that every failure state, from local parameter validation to remote server-side rate limits, is explicitly defined. By using both specific error structures like RateLimitError and sentinel values for service failures, the library enables robust error recovery and clear debugging for integration issues.