Error Handling & Retries

The SDK translates HTTP error codes into strongly typed Go errors and includes built-in retry resilience for transient network and rate limit conditions.

---

Error Hierarchy

All API error responses implement the Go error interface and can be inspected using errors.As:

import (
	"errors"
	"github.com/AdisGroup/shopier-go"
)

res, err := client.Orders.Get(ctx, "invalid_id")
if err != nil {
	var rateLimitErr *shopier.RateLimitError
	var authErr *shopier.AuthenticationError
	var apiErr *shopier.APIError

	switch {
	case errors.As(err, &rateLimitErr):
		// 429 Too Many Requests
		fmt.Printf("Rate limit reached. Retry after: %s\n", rateLimitErr.RetryAfter)

	case errors.As(err, &authErr):
		// 401 Unauthorized
		fmt.Println("Invalid or expired API token. Please refresh credentials.")

	case errors.As(err, &apiErr):
		// 400 Bad Request, 404 Not Found, 403 Forbidden, 5xx etc.
		fmt.Printf("API Error [%d]: %s (Detail: %s)\n",
			apiErr.StatusCode,
			apiErr.ErrorCode,
			apiErr.Message,
		)
		// Access raw response payload if needed
		fmt.Println("Raw JSON:", string(apiErr.RawBody))

	default:
		// Context timeout, connection drop, DNS failure
		fmt.Printf("Network/Transport Error: %v\n", err)
	}
}

---

Common HTTP Error Codes

Status Code	Error Type	Cause & Resolution
400 Bad Request	invalid_request / validation_failed	One or more parameters are missing or invalid. Check request struct fields.
401 Unauthorized	unauthorized	The API token / PAT is missing, malformed, or expired.
403 Forbidden	forbidden	The token lacks necessary scopes, or the endpoint (e.g. /v1/products) requires store-level permission. Contact hello@shopier.com.
404 Not Found	not_found	The requested entity (order ID, product ID, etc.) does not exist.
429 Too Many Requests	rate_limit_exceeded	Sliding window quota reached (200 req/min). Automatically retried by the SDK.
500 / 503 / 504	server_error	Temporary Shopier backend downtime. Automatically retried with exponential backoff.

---

Rate Limit Policy

Shopier limits API throughput on a 60-second sliding window:

• Standard quota: 200 requests / minute per application-user pair.
• When the threshold is exceeded, Shopier returns HTTP 429 Too Many Requests with a Retry-After: <seconds> header.

Automated Rate Limit Handling

The client automatically detects 429 responses, extracts the Retry-After header value, pauses the goroutine until the window resets, and retries the request transparently up to WithMaxRetries(n).

client, err := shopier.NewClient("token",
	shopier.WithMaxRetries(3), // Will retry up to 3 times on 429 and 5xx
)

---

Exponential Backoff & Jitter for 5xx Errors

When Shopier returns transient server errors (500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout), the client calculates an exponential backoff with randomized jitter:

$$\text{delay} = \min(\text{initialDelay} \times 2^{\text{attempt}}, \text{maxDelay}) + \text{jitter}$$

This prevents thundering herd issues on high-volume workers.