Errors

Use normalized Error values and ErrorCode constants to handle provider failures consistently.

Error codes

const (
	ErrNotFound     ErrorCode = "NotFound"
	ErrUnauthorized ErrorCode = "Unauthorized"
	ErrConflict     ErrorCode = "Conflict"
	ErrReadOnly     ErrorCode = "ReadOnly"
	ErrProvider     ErrorCode = "Provider"
)

Handle a missing key

_, err := client.Download(ctx, "missing.txt", files.DownloadOptions{})
if err != nil {
	if files.IsCode(err, files.ErrNotFound) {
		fmt.Println("file is missing")
		return nil
	}
	return err
}

Inspect error details

_, err := client.Head(ctx, "missing.txt", files.OperationOptions{})
if err != nil {
	var filesErr *files.Error
	if errors.As(err, &filesErr) {
		fmt.Println(filesErr.Code)
		fmt.Println(filesErr.TimedOut)
		fmt.Println(filesErr.Aborted)
	}
	return err
}

Create provider errors

Adapter authors should wrap provider-specific failures in files.Error.

return files.NewError(files.ErrProvider, "storage backend rejected the request", err)

Use NewPermanentError for errors that retries should not attempt again.

StoredFile

StoredFile represents downloaded content or object metadata returned by Download, Head, List, and ListAll.

Hooks

Observe actions, errors, and retries from one client-level configuration point.

On this page

Error codes Handle a missing key Inspect error details Create provider errors