This library provides a set of common error definitions used across various API interactions. By using this library, you can achieve consistent error handling in your applications, making it easier to debug, maintain, and integrate with different services.

It is utilized by all API libraries within the go-api-libs organization.

Features

• Wrap Errors: Easily wrap underlying errors with API-specific errors to provide more context.
• Error Identification: Check and identify the nature of errors using Go's errors.Is and errors.As functions.
• Custom Errors: Define and use custom errors specific to your API needs.
• Status Code Handling: Handle and identify errors based on HTTP status codes.
• Content Type Handling: Handle errors based on content type mismatches.

Usage

To install the library, run:

go get github.com/go-api-libs/api

Here is a basic example of how to use the api library for error handling:

package main

import (
	"context"
	"errors"
	"fmt"
	"os"
	"time"

	"github.com/go-api-libs/api"
	"github.com/go-api-libs/toggl/pkg/toggl"
)

func main() {
	c, err := toggl.NewClientWithAPIToken(os.Getenv("TOGGL_TOKEN"))
	if err != nil {
		panic(err)
	}

	ctx := context.Background()
	now := time.Now()
	entries, err := c.ListTimeEntriesInRange(ctx, now.Add(-24*time.Hour), now)
	if err != nil {
		decErr := &api.DecodingError{}
		if errors.As(err, &decErr) {
			fmt.Println("Could not decode response:", decErr.Err)
		}

		apiErr := &api.Error{}
		if errors.As(err, &apiErr) {
			fmt.Println("Response Status Code:", apiErr.StatusCode())
			fmt.Println("Response Content Type:", apiErr.ContentType())
			if apiErr.IsCustom {
				fmt.Println("API sent back the error:", apiErr.Err)
				return
			}
		}

		if errors.Is(err, api.ErrStatusCode) {
			fmt.Println("The response status code indicates an error (but is properly documented).")
			// NOTE: Some APIs have custom error responses that don't contain api.ErrStatusCode.
			// If the status code indicates an error and the API returns a JSON,
			// we unmarshal it and return it as an object that fulfils the error interface.
			// If this happens, `IsCustom` above is set to true.
		} else if errors.Is(err, api.ErrUnknownStatusCode) {
			fmt.Println("The returned status code is not documented in the API specification.")
		}

		if errors.Is(err, api.ErrUnknownContentType) {
			fmt.Println("The response content type is not documented in the API specification.")
		}

		panic(err)
	}

	// Use entries slice
}

Additional Information

• Go Reference: API documentation.

Contributing

Contributions are welcome — please open an issue or a pull request on GitHub.

License

This project is licensed under the Apache 2.0 License.