fix: method-aware retries and five audit findings

- Retries now match the TS/Py idempotency contract: GET, PUT and
  DELETE retry on connection errors and 408/429/500/502/503/504;
  POST and PATCH retry only on 429/503, where the server provably did
  no work. Previously a POST /shorten answered 500 or 504 was
  replayed and could create duplicate links.
- ExportLink hits /api/v1/export/links/{id}: only the per-link route
  names the download after the link, so aggregate exports of
  different links no longer overwrite each other on disk. Aggregate
  slicing stays reachable via Export with a url_id filter.
- Error.Code docs and test fixtures now show the backend's real
  lowercase snake_case codes (conflict, not_found, blocked, ...) with
  the one uppercase outlier EMAIL_NOT_VERIFIED named.
- ListURLsOptions covers the full filter object: CreatedAfter,
  CreatedBefore, and tri-state PasswordSet / MaxClicksSet via
  Opt[bool].
- LinkStats and ExportLink reject the aggregate-only short_code and
  url_id filters client-side instead of letting the endpoint 422.
- 451 affordance: IsBlocked predicate plus the ErrLinkBlocked
  sentinel, attached in newError, for the live safety takedown.

Author: Zingzy

README.md

@@ -169,7 +169,7 @@ metadata. Retrieve it with `errors.As`:
 | What you get | Where |
 | --- | --- |
 | HTTP status | `err.StatusCode` |
-| Machine-readable code | `err.Code` (open string enum, e.g. `CONFLICT_ERROR`) |
+| Machine-readable code | `err.Code` (lowercase snake_case, e.g. `conflict`, `not_found`, `blocked`; the one uppercase outlier is `EMAIL_NOT_VERIFIED`) |
 | Human-readable message | `err.Message`, plus `err.Field` on validation errors |
 | Request id for support | `err.RequestID` |
 | Rate-limit state | `err.RateLimit` (limit, remaining, reset, retry-after) |
@@ -182,13 +182,16 @@ Common branches have predicates and sentinels:
 | `spoo.IsRateLimited(err)` | 429: budget exhausted even after retries |
 | `errors.Is(err, spoo.ErrSessionExpired)` | the refresh token no longer works; log in again |
 | `errors.Is(err, spoo.ErrLinkPasswordProtected)` | the link's stats need the link password |
+| `spoo.IsBlocked(err)` | 451: the link was taken down by the safety pipeline |
 
 ## Retries
 
-Connection errors, 408, 429, and 5xx responses are retried twice by default
-with exponential backoff and jitter. A `Retry-After` header is authoritative
-when the server sends one. Configure with `option.WithMaxRetries(n)`; 0
-disables retries.
+Idempotent requests (GET, PUT, DELETE) are retried twice by default on
+connection errors and 408, 429, 500, 502, 503 and 504 responses, with
+exponential backoff and jitter. Requests that are not idempotent are only
+retried when the server provably did no work (429 and 503). A `Retry-After`
+header is authoritative when the server sends one. Configure with
+`option.WithMaxRetries(n)`; 0 disables retries.
 
 ## Pagination
 
@@ -247,7 +250,7 @@ file, or database, and rotated tokens persist through it.
 | `BulkDelete`, `BulkUpdateStatus`, `BulkUpdateExpiry`, `BulkMoveDomain` | `POST /api/v1/urls/bulk/*` |
 | `Stats`, `LinkStats`, `StatsByAlias` | `GET /api/v1/stats`, `GET /api/v1/stats/links/{id}` |
 | `PublicStats`, `PublicPreview` | `GET or POST /api/v1/public/stats/{code}`, `GET /api/v1/public/preview/{code}` |
-| `Export`, `ExportLink` | `GET /api/v1/export` |
+| `Export`, `ExportLink` | `GET /api/v1/export`, `GET /api/v1/export/links/{id}` |
 | `EmojiSet` | `GET /api/v1/emoji-set` (ETag-cached) |
 | `Me` | `GET /auth/me` |
 | `ExchangeDeviceCode`, `RefreshTokens`, `DeviceAuthURL` | `POST /auth/device/token`, `POST /auth/device/refresh` |

client.go

@@ -129,8 +129,9 @@ func (c *Client) request(ctx context.Context, method, path string, query url.Val
 }
 
 // send builds and performs one HTTP call, retrying transient failures
-// (connection errors, 408, 429, 5xx) with exponential backoff and
-// jitter, honoring Retry-After. Callers own the response body.
+// with exponential backoff and jitter, honoring Retry-After. What
+// counts as transient depends on the method: see
+// transport.RetryableStatus. Callers own the response body.
 func (c *Client) send(ctx context.Context, method, path string, query url.Values, body any, creds Credentials, extra http.Header) (*http.Response, error) {
 	u := c.base + path
 	if len(query) > 0 {
@@ -147,10 +148,12 @@ func (c *Client) send(ctx context.Context, method, path string, query url.Values
 	for attempt := 0; ; attempt++ {
 		resp, err := c.sendOnce(ctx, method, u, payload, creds, extra)
 		if err != nil {
-			if attempt >= c.maxRetries || ctx.Err() != nil {
+			// A dropped connection may have reached the server, so
+			// only idempotent methods replay on transport errors.
+			if !transport.IdempotentMethod(method) || attempt >= c.maxRetries || ctx.Err() != nil {
 				return nil, err
 			}
-		} else if !transport.RetryableStatus(resp.StatusCode) || attempt >= c.maxRetries {
+		} else if !transport.RetryableStatus(method, resp.StatusCode) || attempt >= c.maxRetries {
 			return resp, nil
 		}
 		var retryAfter string

client_test.go

@@ -64,7 +64,7 @@ func TestClientHeaderRejectsMalformedVersion(t *testing.T) {
 func TestDoParsesErrorEnvelope(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusConflict)
-		w.Write([]byte(`{"error":"alias already taken","code":"CONFLICT_ERROR","field":"alias"}`))
+		w.Write([]byte(`{"error":"alias already taken","code":"conflict","field":"alias"}`))
 	}))
 	defer srv.Close()
 
@@ -74,7 +74,7 @@ func TestDoParsesErrorEnvelope(t *testing.T) {
 	if !errors.As(err, &apiErr) {
 		t.Fatalf("err = %v, want *Error", err)
 	}
-	if apiErr.StatusCode != 409 || apiErr.Code != "CONFLICT_ERROR" || apiErr.Message != "alias already taken" {
+	if apiErr.StatusCode != 409 || apiErr.Code != "conflict" || apiErr.Message != "alias already taken" {
 		t.Fatalf("unexpected Error: %+v", apiErr)
 	}
 	if apiErr.Field != "alias" {
@@ -95,7 +95,7 @@ func TestDoRefreshesOn401AndRetries(t *testing.T) {
 			}
 			calls.Add(1)
 			w.WriteHeader(http.StatusUnauthorized)
-			w.Write([]byte(`{"error":"token expired","code":"AUTHENTICATION_ERROR"}`))
+			w.Write([]byte(`{"error":"token expired","code":"authentication_error"}`))
 		}
 	}))
 	defer srv.Close()

device_test.go

@@ -218,7 +218,7 @@ func TestConcurrent401sRefreshOnce(t *testing.T) {
 				// A second spend of a rotated token is exactly the
 				// bug: fail the way the backend would.
 				w.WriteHeader(http.StatusUnauthorized)
-				w.Write([]byte(`{"error":"invalid refresh token","code":"AUTHENTICATION_ERROR"}`))
+				w.Write([]byte(`{"error":"invalid refresh token","code":"authentication_error"}`))
 				return
 			}
 			time.Sleep(50 * time.Millisecond) // widen the race window
@@ -229,7 +229,7 @@ func TestConcurrent401sRefreshOnce(t *testing.T) {
 				return
 			}
 			w.WriteHeader(http.StatusUnauthorized)
-			w.Write([]byte(`{"error":"token expired","code":"AUTHENTICATION_ERROR"}`))
+			w.Write([]byte(`{"error":"token expired","code":"authentication_error"}`))
 		}
 	}))
 	defer srv.Close()

doc.go

@@ -57,9 +57,11 @@
 //
 // # Retries
 //
-// Transient failures (connection errors, 408, 429, 5xx) are retried
-// twice by default with exponential backoff and jitter, honoring
-// Retry-After. Tune with option.WithMaxRetries.
+// Idempotent requests (GET, PUT, DELETE) are retried twice by default
+// on connection errors and 408, 429, 500, 502, 503 and 504, with
+// exponential backoff and jitter, honoring Retry-After. Requests that
+// are not idempotent are only retried when the server provably did no
+// work (429 and 503). Tune with option.WithMaxRetries.
 //
 // # Pagination
 //

errors.go

@@ -23,8 +23,14 @@ var (
 
 	// ErrLinkPasswordProtected marks a 401 that is a property of the
 	// link, not of the session: the link's stats require the link
-	// password, which the SDK does not supply.
+	// password, supplied via PublicStatsQuery.Password.
 	ErrLinkPasswordProtected = errors.New("link is password protected")
+
+	// ErrLinkBlocked marks a 451: the link was taken down by the
+	// safety pipeline because its destination was flagged. This is a
+	// verdict on the link, not a transient failure — see also
+	// [IsBlocked].
+	ErrLinkBlocked = errors.New("link is blocked")
 )
 
 // ErrTokenSourceRequired is returned by [Client.ForceRefresh] when the
@@ -52,10 +58,13 @@ type RateLimit struct {
 type Error struct {
 	// StatusCode is the HTTP status of the response.
 	StatusCode int `json:"-"`
-	// Code is the backend's machine-readable error code, an open enum
-	// (e.g. "CONFLICT_ERROR", "AUTHENTICATION_ERROR"). Read from the
-	// body, with the X-Error-Code header as fallback for the
-	// edge-composed responses whose bodies carry no envelope.
+	// Code is the backend's machine-readable error code, an open
+	// string enum in lowercase snake_case: "conflict",
+	// "authentication_error", "not_found", "rate_limit_exceeded",
+	// "payload_too_large", "blocked", "gone", and so on. The one
+	// uppercase outlier is "EMAIL_NOT_VERIFIED". Read from the body,
+	// with the X-Error-Code header as fallback for the edge-composed
+	// responses whose bodies carry no envelope.
 	Code string `json:"code"`
 	// Message is the human-readable error message.
 	Message string `json:"error"`
@@ -97,6 +106,15 @@ func IsRateLimited(err error) bool {
 	return errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusTooManyRequests
 }
 
+// IsBlocked reports whether err is an API 451: the link was taken down
+// by the safety pipeline. Integrators should branch on this to tell
+// "the link was removed" apart from "something broke".
+// errors.Is(err, ErrLinkBlocked) reports the same condition.
+func IsBlocked(err error) bool {
+	var apiErr *Error
+	return errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusUnavailableForLegalReasons
+}
+
 // newError builds an *Error from an HTTP error response, consuming (but
 // not closing) the body.
 func newError(resp *http.Response) *Error {
@@ -108,11 +126,14 @@ func newError(resp *http.Response) *Error {
 	}
 	e.RequestID = resp.Header.Get("X-Request-ID")
 	e.RateLimit = parseRateLimit(resp.Header)
-	if resp.StatusCode == http.StatusUnauthorized {
+	switch resp.StatusCode {
+	case http.StatusUnauthorized:
 		switch resp.Header.Get("X-Error-Code") {
 		case "password_required", "invalid_password":
 			e.sentinel = ErrLinkPasswordProtected
 		}
+	case http.StatusUnavailableForLegalReasons:
+		e.sentinel = ErrLinkBlocked
 	}
 	return e
 }

errors_test.go

@@ -19,7 +19,7 @@ func TestErrorParsesRateLimitAndRequestID(t *testing.T) {
 		w.Header().Set("X-RateLimit-Reset", "1755500000")
 		w.Header().Set("Retry-After", "30")
 		w.WriteHeader(http.StatusTooManyRequests)
-		w.Write([]byte(`{"error":"rate limit exceeded","code":"RATE_LIMIT_ERROR"}`))
+		w.Write([]byte(`{"error":"rate limit exceeded","code":"rate_limit_exceeded"}`))
 	}))
 	defer srv.Close()
 
@@ -47,6 +47,52 @@ func TestErrorParsesRateLimitAndRequestID(t *testing.T) {
 	}
 }
 
+// 451 is the live safety takedown: integrators branch on it to tell
+// "the link was removed" apart from "something broke".
+func TestBlocked451(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("X-Error-Code", "blocked")
+		w.WriteHeader(http.StatusUnavailableForLegalReasons)
+		w.Write([]byte(`{"error":"This link has been blocked","code":"blocked"}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(option.WithBaseURL(srv.URL))
+	_, err := c.PublicStats(context.Background(), "scam", PublicStatsQuery{})
+	if !IsBlocked(err) {
+		t.Fatalf("err = %v, want IsBlocked", err)
+	}
+	if !errors.Is(err, ErrLinkBlocked) {
+		t.Fatalf("err = %v, want ErrLinkBlocked sentinel", err)
+	}
+	var apiErr *Error
+	if !errors.As(err, &apiErr) || apiErr.Code != "blocked" {
+		t.Fatalf("err = %v, want code blocked", err)
+	}
+	if IsBlocked(&Error{StatusCode: 404}) {
+		t.Fatal("404 must not read as blocked")
+	}
+}
+
+// An edge-composed 451 whose body is HTML still yields a usable code
+// via the X-Error-Code header fallback.
+func TestBlocked451EdgeComposedBody(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("X-Error-Code", "blocked")
+		w.Header().Set("Content-Type", "text/html")
+		w.WriteHeader(http.StatusUnavailableForLegalReasons)
+		w.Write([]byte(`<!doctype html><title>451</title>`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(option.WithBaseURL(srv.URL))
+	_, err := c.Me(context.Background())
+	var apiErr *Error
+	if !errors.As(err, &apiErr) || apiErr.Code != "blocked" || !IsBlocked(err) {
+		t.Fatalf("err = %v, want header-derived blocked code", err)
+	}
+}
+
 func TestIsRateLimitedRejectsOtherErrors(t *testing.T) {
 	if IsRateLimited(errors.New("nope")) {
 		t.Fatal("plain errors must not read as rate-limited")
@@ -65,11 +111,11 @@ func TestRefreshRejectionIsSessionExpired(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/auth/device/refresh" {
 			w.WriteHeader(http.StatusUnauthorized)
-			w.Write([]byte(`{"error":"invalid refresh token","code":"AUTHENTICATION_ERROR"}`))
+			w.Write([]byte(`{"error":"invalid refresh token","code":"authentication_error"}`))
 			return
 		}
 		w.WriteHeader(http.StatusUnauthorized)
-		w.Write([]byte(`{"error":"token expired","code":"AUTHENTICATION_ERROR"}`))
+		w.Write([]byte(`{"error":"token expired","code":"authentication_error"}`))
 	}))
 	defer srv.Close()
 
@@ -89,7 +135,7 @@ func TestRefreshRejectionIsSessionExpired(t *testing.T) {
 func TestPlain401IsNotSessionExpired(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusUnauthorized)
-		w.Write([]byte(`{"error":"authentication required","code":"AUTHENTICATION_ERROR"}`))
+		w.Write([]byte(`{"error":"authentication required","code":"authentication_error"}`))
 	}))
 	defer srv.Close()
 

export.go

@@ -26,23 +26,29 @@ type ExportFile struct {
 // Export downloads account-wide stats in the given format (json, csv,
 // xlsx, xml). Auth is required — anonymous export no longer exists.
 // Slice to specific links with the short_code / url_id filters on
-// [StatsQuery].
+// [StatsQuery]; note the aggregate route reports a generic filename
+// regardless of slicing, so single-link exports belong on ExportLink.
 func (c *Client) Export(ctx context.Context, q StatsQuery, format string) (*ExportFile, error) {
-	return c.export(ctx, q.values(), format)
+	return c.export(ctx, "/api/v1/export", q.values(), format)
 }
 
-// ExportLink downloads one owned link's stats by its url id (resolve
-// an alias with ResolveAlias first). Unknown and foreign ids yield an
-// empty slice of that link, consistent with the slicing filters.
+// ExportLink downloads one owned link's stats by its url id via the
+// per-link route, whose server-suggested filename carries the link's
+// identity (the aggregate route names every download the same, so
+// saved files would silently overwrite each other). Resolve an alias
+// with ResolveAlias first; unknown and foreign ids both 404. The
+// short_code / url_id slicing filters are aggregate-only here too.
 func (c *Client) ExportLink(ctx context.Context, urlID string, q StatsQuery, format string) (*ExportFile, error) {
-	v := q.values()
-	v.Set("url_id", urlID)
-	return c.export(ctx, v, format)
+	if err := q.validatePerLink(); err != nil {
+		return nil, err
+	}
+	path := "/api/v1/export/links/" + url.PathEscape(urlID)
+	return c.export(ctx, path, q.values(), format)
 }
 
-func (c *Client) export(ctx context.Context, v url.Values, format string) (*ExportFile, error) {
+func (c *Client) export(ctx context.Context, path string, v url.Values, format string) (*ExportFile, error) {
 	v.Set("format", format)
-	resp, err := c.request(ctx, http.MethodGet, "/api/v1/export", v, nil)
+	resp, err := c.request(ctx, http.MethodGet, path, v, nil)
 	if err != nil {
 		return nil, err
 	}

internal/transport/transport.go

@@ -20,12 +20,34 @@ const (
 	retryMaxDelay = 10 * time.Second
 )
 
-// RetryableStatus reports whether a response status is worth retrying:
-// timeouts, rate limits, and server-side failures.
-func RetryableStatus(status int) bool {
-	return status == http.StatusRequestTimeout ||
-		status == http.StatusTooManyRequests ||
-		status >= 500
+// IdempotentMethod reports whether an HTTP method is safe to replay
+// unconditionally. The set matches the TS and Python SDKs exactly:
+// GET, PUT, DELETE.
+func IdempotentMethod(method string) bool {
+	switch method {
+	case http.MethodGet, http.MethodPut, http.MethodDelete:
+		return true
+	}
+	return false
+}
+
+// RetryableStatus reports whether a response status is worth retrying
+// for the given method. Idempotent methods retry on 408, 429, 500,
+// 502, 503 and 504. Non-idempotent methods (POST, PATCH) retry only on
+// 429 and 503, the statuses where the server provably did no work; a
+// replayed POST after a 500 or 504 could have created the resource
+// twice. The sets match the TS and Python SDKs exactly.
+func RetryableStatus(method string, status int) bool {
+	switch status {
+	case http.StatusTooManyRequests, http.StatusServiceUnavailable:
+		return true
+	case http.StatusRequestTimeout,
+		http.StatusInternalServerError,
+		http.StatusBadGateway,
+		http.StatusGatewayTimeout:
+		return IdempotentMethod(method)
+	}
+	return false
 }
 
 // RetryDelay computes the wait before retry number attempt+1. A