Pagination & Rate Limiting
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Go SDK manages large datasets through cursor-based pagination and provides specialized error handling for API rate limits. These systems ensure efficient data retrieval across resources like emails, contacts, and domains while maintaining client reliability when hitting service quotas.
Pagination
The SDK implements cursor-based pagination for list operations. You control the result set using a standard ListOptions structure that defines the page size and relative position in the dataset.
Pagination Logic and Components
Pagination relies on three primary parameters: Limit, After, and Before. The API returns a boolean HasMore flag in response objects to indicate if additional records exist.
The diagram shows the iterative flow of fetching paginated data using the After cursor.
Sources: resend.go:375-379, examples/with_pagination.go:39-44
Pagination Parameters
| Field | Type | Description |
|---|---|---|
Limit | *int | Number of results to return per page. |
After | *string | Cursor ID to retrieve records following this element. |
Before | *string | Cursor ID to retrieve records preceding this element. |
Sources: resend.go:375-379
Implementation Example
When you fetch a list, the SDK builds a query string based on the provided options. If HasMore is true, you use the ID of the last item in the current slice to fetch the next page.
limit := 10
after := "last-item-id"
apiKeysResp, err := client.ApiKeys.ListWithOptions(ctx, &resend.ListOptions{
Limit: &limit,
After: &after,
})
Sources: examples/with_pagination.go:42-47, resend.go:382-404
Rate Limiting
Resend enforces rate limits to ensure service stability. The SDK captures these limits from HTTP headers and exposes them via a dedicated error type.
Rate Limit Error Architecture
When the API returns an HTTP 429 status code, the SDK's internal handleError function parses the response headers into a RateLimitError. This allows you to inspect specific quotas and wait times.
The diagram illustrates the sequence of identifying and reacting to a rate limit event.
Sources: resend.go:281-299, examples/handle_rate_limit.go:34-40
Rate Limit Fields
| Field | Header Source | Description |
|---|---|---|
Message | Body | Error message from the API. |
Limit | ratelimit-limit | Total request limit for the window. |
Remaining | ratelimit-remaining | Remaining requests in the current window. |
Reset | ratelimit-reset | Seconds until the limit resets. |
RetryAfter | retry-after | Seconds to wait before retrying the request. |
Sources: resend.go:292-297, resend_test.go:88-100
Rate Limit Monitoring
You can programmatically check your current usage and rate limit status by calling the Usage service. This returns the configured limit and duration for your account.
usage, err := client.Usage.Get()
fmt.Printf("Rate Limit: %d per %s", usage.RateLimit.Limit, usage.RateLimit.Duration)
Sources: usage_test.go:45-46, usage_test.go:87-88
Conclusion
Pagination in the Resend SDK allows for predictable memory usage when handling large lists of resources through cursor navigation. Simultaneously, the rate limiting system provides transparent feedback through headers, enabling robust retry logic and usage monitoring to maintain high availability in production environments.