feat: support rate limits

Return enriched error if we are rate limited for the caller to handle.

Author: martinohansen

accounts.go

@@ -93,7 +93,7 @@ func (c Client) GetAccountMetadata(id string) (AccountMetadata, error) {
 			Path: strings.Join([]string{accountPath, id, ""}, "/"),
 		},
 	}
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return AccountMetadata{}, err
@@ -123,7 +123,7 @@ func (c Client) GetAccountBalances(id string) (AccountBalances, error) {
 			Path: strings.Join([]string{accountPath, id, balancesPath, ""}, "/"),
 		},
 	}
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return AccountBalances{}, err
@@ -153,7 +153,7 @@ func (c Client) GetAccountDetails(id string) (AccountDetails, error) {
 			Path: strings.Join([]string{accountPath, id, detailsPath, ""}, "/"),
 		},
 	}
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return AccountDetails{}, err
@@ -183,7 +183,7 @@ func (c Client) GetAccountTransactions(id string) (AccountTransactions, error) {
 			Path: strings.Join([]string{accountPath, id, transactionsPath, ""}, "/"),
 		},
 	}
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return AccountTransactions{}, err

agreements.go

@@ -39,7 +39,7 @@ func (c Client) CreateEndUserAgreement(eua EndUserAgreement) (EndUserAgreement,
 	}
 	req.Body = io.NopCloser(bytes.NewBuffer(data))
 
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return EndUserAgreement{}, err

client.go

@@ -4,7 +4,9 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"net/http"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -103,3 +105,55 @@ func NewClient(secretId, secretKey string) (*Client, error) {
 
 	return c, nil
 }
+
+// do sends the HTTP request and returns a RateLimitError when the response code
+// indicates that the request was throttled.
+func (c *Client) do(req *http.Request) (*http.Response, error) {
+	resp, err := c.c.Do(req)
+	if err != nil {
+		return nil, err
+	}
+
+	if resp.StatusCode == http.StatusTooManyRequests {
+		// We have been rate limited, parse the response and return a
+		// RateLimitError for the caller to handle.
+		body, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+
+		rl := parseRateLimit(resp.Header)
+		return nil, &RateLimitError{APIError: &APIError{StatusCode: resp.StatusCode, Body: string(body)}, RateLimit: rl}
+	}
+
+	return resp, nil
+}
+
+// parseRateLimit extracts rate limit information from the HTTP headers
+// https://bankaccountdata.zendesk.com/hc/en-gb/articles/11529584398236-Bank-API-Rate-Limits-and-Rate-Limit-Headers
+func parseRateLimit(h http.Header) RateLimit {
+	toInt := func(v string) int {
+		i, _ := strconv.Atoi(v)
+		return i
+	}
+
+	rl := RateLimit{}
+
+	if v := h.Get("HTTP_X_RATELIMIT_ACCOUNT_SUCCESS_LIMIT"); v != "" {
+		rl.Limit = toInt(v)
+	} else {
+		rl.Limit = toInt(h.Get("HTTP_X_RATELIMIT_LIMIT"))
+	}
+
+	if v := h.Get("HTTP_X_RATELIMIT_ACCOUNT_SUCCESS_REMAINING"); v != "" {
+		rl.Remaining = toInt(v)
+	} else {
+		rl.Remaining = toInt(h.Get("HTTP_X_RATELIMIT_REMAINING"))
+	}
+
+	if v := h.Get("HTTP_X_RATELIMIT_ACCOUNT_SUCCESS_RESET"); v != "" {
+		rl.Reset = toInt(v)
+	} else {
+		rl.Reset = toInt(h.Get("HTTP_X_RATELIMIT_RESET"))
+	}
+
+	return rl
+}

client_test.go

@@ -2,7 +2,9 @@ package nordigen
 
 import (
 	"context"
+	"errors"
 	"net/http"
+	"net/http/httptest"
 	"os"
 	"sync"
 	"testing"
@@ -72,3 +74,45 @@ func TestRefreshRefresh(t *testing.T) {
 	}
 	cancel() // Stop handler again
 }
+
+func TestRateLimitError(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("HTTP_X_RATELIMIT_LIMIT", "10")
+		w.Header().Set("HTTP_X_RATELIMIT_REMAINING", "0")
+		w.Header().Set("HTTP_X_RATELIMIT_RESET", "5")
+		w.WriteHeader(http.StatusTooManyRequests)
+		w.Write([]byte("rate limited"))
+	}))
+	defer ts.Close()
+
+	c := &Client{c: ts.Client()}
+	req, err := http.NewRequest(http.MethodGet, ts.URL, nil)
+	if err != nil {
+		t.Errorf("NewRequest: %v", err)
+	}
+
+	resp, err := c.do(req)
+	if err == nil {
+		t.Errorf("expected error")
+	}
+	if resp != nil {
+		t.Errorf("expected nil response")
+	}
+
+	rlErr, ok := err.(*RateLimitError)
+	if !ok {
+		t.Errorf("expected RateLimitError got %T", err)
+	}
+	if rlErr.RateLimit.Limit != 10 || rlErr.RateLimit.Remaining != 0 || rlErr.RateLimit.Reset != 5 {
+		t.Errorf("unexpected rate limit values: %+v", rlErr.RateLimit)
+	}
+
+	// Error should unwrap
+	var apiErr *APIError
+	if !errors.As(err, &apiErr) {
+		t.Errorf("expected APIError, got %T", err)
+	}
+	if !errors.Is(err, apiErr) {
+		t.Errorf("expected %v, got %v", apiErr, err)
+	}
+}

errors.go

@@ -1,6 +1,9 @@
 package nordigen
 
-import "fmt"
+import (
+	"fmt"
+	"time"
+)
 
 type APIError struct {
 	StatusCode int
@@ -15,3 +18,31 @@ func (e *APIError) Error() string {
 func (e *APIError) Unwrap() error {
 	return e.Err
 }
+
+// RateLimit contains information from rate limit headers.
+type RateLimit struct {
+	Limit     int // Maximum number of requests allowed
+	Remaining int // Requests remaining before hitting the limit
+	Reset     int // Seconds until the limit resets
+}
+
+// RateLimitError is returned when the API responds with HTTP 429. It embeds the
+// APIError and exposes the parsed rate limit headers so callers can decide how
+// to handle the throttling.
+type RateLimitError struct {
+	*APIError
+	RateLimit RateLimit
+}
+
+// Resets returns the duration until the rate limit resets
+func (rl RateLimitError) Resets() time.Duration {
+	return time.Duration(rl.RateLimit.Reset) * time.Second
+}
+
+func (e *RateLimitError) Error() string {
+	return fmt.Sprintf("RateLimitError %v limit=%d remaining=%d reset=%d", e.StatusCode, e.RateLimit.Limit, e.RateLimit.Remaining, e.RateLimit.Reset)
+}
+
+func (e *RateLimitError) Unwrap() error {
+	return e.APIError
+}

go.mod

@@ -1,3 +1,3 @@
 module github.com/frieser/nordigen-go-lib/v2
 
-go 1.16
+go 1.24

institutions.go

@@ -31,7 +31,7 @@ func (c Client) ListInstitutions(country string) ([]Institution, error) {
 	q.Add(countryParam, country)
 	req.URL.RawQuery = q.Encode()
 
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return nil, err
@@ -61,7 +61,7 @@ func (c Client) GetInstitution(institutionID string) (Institution, error) {
 			Path: strings.Join([]string{institutionsPath, institutionID, ""}, "/"),
 		},
 	}
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return Institution{}, err

requisitions.go

@@ -49,7 +49,7 @@ func (c Client) CreateRequisition(r Requisition) (Requisition, error) {
 	}
 	req.Body = io.NopCloser(bytes.NewBuffer(data))
 
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return Requisition{}, err
@@ -78,7 +78,7 @@ func (c Client) GetRequisition(id string) (r Requisition, err error) {
 			Path: strings.Join([]string{requisitionsPath, id, ""}, "/"),
 		},
 	}
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 
 	if err != nil {
 		return Requisition{}, err
@@ -128,7 +128,7 @@ func (c Client) fetchRequisitions(u *url.URL, allRequisitions *[]Requisition) er
 		URL:    u,
 	}
 
-	resp, err := c.c.Do(&req)
+	resp, err := c.do(&req)
 	if err != nil {
 		return err
 	}

token.go

@@ -52,7 +52,7 @@ func (c *Client) newToken(ctx context.Context) error {
 	}
 	req = req.WithContext(ctx)
 
-	resp, err := c.c.Do(req)
+	resp, err := c.do(req)
 	if err != nil {
 		return err
 	}
@@ -94,7 +94,7 @@ func (c *Client) refreshToken(ctx context.Context) error {
 	}
 	req = req.WithContext(ctx)
 
-	resp, err := c.c.Do(req)
+	resp, err := c.do(req)
 	if err != nil {
 		return err
 	}