errors

Documentation

Overview

Package errors provides structured error types and factory functions for the Notion CLI. All errors are represented as NotionCLIError, which includes an error code, human-readable message, optional details, and user-facing suggestions for resolution.

Index

• Constants
• type NotionCLIError
  • func FromNotionAPI(statusCode int, body map[string]any) *NotionCLIError
  • func InvalidIDFormat(id string) *NotionCLIError
  • func InvalidJSON(detail string) *NotionCLIError
  • func OAuthCancelled() *NotionCLIError
  • func OAuthFailed(detail string) *NotionCLIError
  • func OAuthNotConfigured() *NotionCLIError
  • func OAuthPortInUse(ports []int) *NotionCLIError
  • func OAuthStateMismatch() *NotionCLIError
  • func OAuthTimeout() *NotionCLIError
  • func RateLimited(retryAfter string) *NotionCLIError
  • func TokenInvalid(detail string) *NotionCLIError
  • func TokenMissing() *NotionCLIError
  • func WorkspaceNotSynced() *NotionCLIError
  • func (e *NotionCLIError) Error() string
  • func (e *NotionCLIError) ExitCode() int
  • func (e *NotionCLIError) Unwrap() error

Constants

const (
	ExitSuccess  = 0
	ExitAPIError = 1
	ExitCLIError = 2
)

Exit codes returned by the CLI process.

const (
	CodeUnauthorized        = "UNAUTHORIZED"
	CodeTokenMissing        = "TOKEN_MISSING"
	CodeTokenInvalid        = "TOKEN_INVALID"
	CodeNotFound            = "NOT_FOUND"
	CodeDatabaseNotFound    = "DATABASE_NOT_FOUND"
	CodeDataSourceNotFound  = "data_source_not_found"
	CodePageNotFound        = "PAGE_NOT_FOUND"
	CodeBlockNotFound       = "BLOCK_NOT_FOUND"
	CodeUserNotFound        = "USER_NOT_FOUND"
	CodeInvalidIDFormat     = "INVALID_ID_FORMAT"
	CodeDatabaseIDConfusion = "DATABASE_ID_CONFUSION"
	CodeRateLimited         = "RATE_LIMITED"
	CodeValidationError     = "VALIDATION_ERROR"
	CodeInvalidJSON         = "INVALID_JSON"
	CodeWorkspaceNotSynced  = "WORKSPACE_NOT_SYNCED"
	CodeNetworkError        = "NETWORK_ERROR"
	CodeTimeout             = "TIMEOUT"
	CodeInternalError       = "INTERNAL_ERROR"
	CodeConflict            = "CONFLICT"
	CodeServiceUnavailable  = "SERVICE_UNAVAILABLE"
	CodeInvalidRequest      = "INVALID_REQUEST"
	CodePropertyNotFound    = "PROPERTY_NOT_FOUND"
	CodePermissionDenied    = "PERMISSION_DENIED"
	CodeBadGateway          = "BAD_GATEWAY"
	CodeInvalidFilter       = "INVALID_FILTER"
	CodeInvalidSort         = "INVALID_SORT"
	CodeInvalidProperty     = "INVALID_PROPERTY"
	CodeMissingRequired     = "MISSING_REQUIRED"
	CodeInvalidEnum         = "INVALID_ENUM"
	CodeObjectNotFound      = "OBJECT_NOT_FOUND"
	CodeSizeLimitExceeded   = "SIZE_LIMIT_EXCEEDED"

	// OAuth error codes.
	CodeOAuthFailed        = "OAUTH_FAILED"
	CodeOAuthTimeout       = "OAUTH_TIMEOUT"
	CodeOAuthCancelled     = "OAUTH_CANCELLED"
	CodeOAuthPortInUse     = "OAUTH_PORT_IN_USE"
	CodeOAuthStateMismatch = "OAUTH_STATE_MISMATCH"
	CodeOAuthNotConfigured = "OAUTH_NOT_CONFIGURED"
)

Error code constants. These are stable string identifiers used for programmatic error handling and JSON envelope responses.

Types

type NotionCLIError

type NotionCLIError struct {
	Code        string   `json:"code"`
	Message     string   `json:"message"`
	Details     any      `json:"details,omitempty"`
	Suggestions []string `json:"suggestions,omitempty"`
	HTTPStatus  int      `json:"http_status,omitempty"`
	Err         error    `json:"-"`
}

NotionCLIError is the canonical error type for the CLI. It carries structured information about what went wrong and how to fix it.

func FromNotionAPI

func FromNotionAPI(statusCode int, body map[string]any) *NotionCLIError

FromNotionAPI parses a Notion API error response into a NotionCLIError. The body is expected to contain "code" and "message" keys as returned by the Notion API.

func InvalidIDFormat

func InvalidIDFormat(id string) *NotionCLIError

InvalidIDFormat returns an error for a string that cannot be parsed as a Notion resource ID.

func InvalidJSON

func InvalidJSON(detail string) *NotionCLIError

InvalidJSON returns an error for malformed JSON input.

func OAuthCancelled

func OAuthCancelled() *NotionCLIError

OAuthCancelled returns an error when the user denies the authorization.

func OAuthFailed

func OAuthFailed(detail string) *NotionCLIError

OAuthFailed returns an error when the OAuth token exchange fails.

func OAuthNotConfigured

func OAuthNotConfigured() *NotionCLIError

OAuthNotConfigured returns an error when OAuth credentials are not compiled in.

func OAuthPortInUse

func OAuthPortInUse(ports []int) *NotionCLIError

OAuthPortInUse returns an error when no localhost callback port is available. Ports is the list of ports the CLI tried; all were occupied.

func OAuthStateMismatch

func OAuthStateMismatch() *NotionCLIError

OAuthStateMismatch returns an error when the CSRF state parameter does not match.

func OAuthTimeout

func OAuthTimeout() *NotionCLIError

OAuthTimeout returns an error when the OAuth callback is not received in time.

func RateLimited

func RateLimited(retryAfter string) *NotionCLIError

RateLimited returns an error when the Notion API returns 429.

func TokenInvalid

func TokenInvalid(detail string) *NotionCLIError

TokenInvalid returns an error for a malformed or rejected API token.

func TokenMissing

func TokenMissing() *NotionCLIError

TokenMissing returns an error indicating no API token is configured.

func WorkspaceNotSynced

func WorkspaceNotSynced() *NotionCLIError

WorkspaceNotSynced returns an error when an operation requires workspace data that has not been cached yet.

func (*NotionCLIError) Error

func (e *NotionCLIError) Error() string

Error implements the error interface.

func (*NotionCLIError) ExitCode

func (e *NotionCLIError) ExitCode() int

ExitCode returns the process exit code appropriate for this error.

func (*NotionCLIError) Unwrap

func (e *NotionCLIError) Unwrap() error

Unwrap returns the underlying error, supporting errors.Is/As chains.