apierr

Documentation

Overview

Package apierr defines typed API errors used across lokex.

Package apierr provides parsing helpers for Lokalise-style error payloads.

Lokalise (and some proxies) may return different JSON error shapes. Parse() tries several known patterns and falls back to a generic form, populating APIError with best-effort fields for callers to inspect.

Index

• Constants
• func IsRetryable(err error) bool
• func JitteredBackoff(base time.Duration) time.Duration
• type APIError
  • func Parse(slurp []byte, status int) *APIError
  • func (e *APIError) Error() string

Constants

const DefaultErrCap = 8192

DefaultErrCap is the maximum number of response-body bytes captured when constructing an APIError from a non-2xx response.

Functions

func IsRetryable

func IsRetryable(err error) bool

IsRetryable returns true only for transient failures. Order is important.

func JitteredBackoff

func JitteredBackoff(base time.Duration) time.Duration

JitteredBackoff returns a randomized delay in [0.5*base, 1.5*base). If base <= 0, it falls back to 300ms.

Types

type APIError

type APIError struct {
	// Status is the HTTP status code (for example, 400, 429, or 500).
	Status int

	// Code is a service-specific numeric code, if the API returned one.
	// When absent in the payload, Code typically mirrors Status.
	Code int

	// Message is a human-readable error summary from the server.
	Message string

	// Reason is an optional machine-friendly identifier returned by the server.
	Reason string

	// Details contains arbitrary structured data returned by the API.
	Details map[string]any

	// Raw is the trimmed captured response body. It may be truncated when the
	// response exceeds DefaultErrCap.
	Raw string

	// Resp is the original HTTP response for access to status and headers.
	// Its Body must not be read by callers.
	Resp *http.Response
}

APIError represents a non-2xx response from the Lokalise API or another HTTP service used by lokex.

Callers can inspect Status, Code, Reason, and Details to decide how to handle the error, for example whether it is retryable.

func Parse

func Parse(slurp []byte, status int) *APIError

Parse converts an HTTP error body (already size-limited by caller) and the HTTP status code into a structured *APIError.

• slurp: raw response body bytes (may be empty or non-JSON)
• status: HTTP status code from the response

Supported shapes (examples):

1. Top-level fields: {"message":"msg","statusCode":429,"error":"Too Many Requests"}
2. Nested error: {"error":{"message":"msg","code":429,"details":{"bucket":"global"}}}
3. Alternate top-level with code/errorCode (number or string): {"message":"msg","code":"429","details":{...}}
4. Fallback: preserve "message" and "error" (string) if present; stash all fields in Details.

Non-JSON bodies produce an APIError with Reason "non-json error body" and Raw=trimmed body.

func (*APIError) Error

func (e *APIError) Error() string

Error implements the error interface. It prefers the server-provided message and falls back to the canonical HTTP status text.