Error Types

Overview

The Garnet API uses typed errors from the types/errs package to provide clear, actionable error information. All errors implement the standard Go error interface and support errors.Is for type checking.

InvalidArgumentError

Returned when request parameters are invalid or malformed.

type InvalidArgumentError string

const InvalidArgument = InvalidArgumentError("invalid argument")

Common Causes:

Missing required fields
Invalid enum values
Malformed data (e.g., invalid IP address, bad CIDR notation)
Empty fields where non-empty is required
Fields exceeding maximum length

Example Usage:

if err := agent.Validate(); err != nil {
    if errors.Is(err, errs.InvalidArgument) {
        // Handle invalid argument
    }
}

NotFoundError

Returned when a requested resource does not exist.

type NotFoundError string

const NotFound = NotFoundError("not found")

Common Causes:

Resource ID doesn’t exist
Resource was deleted
User doesn’t have access to the resource

Specific Errors:

ErrAgentNotFound         = errs.NotFoundError("agent not found")
ErrEventNotFound         = errs.NotFoundError("event not found")
ErrNetworkPolicyNotFound = errs.NotFoundError("network policy not found")
ErrWebhookNotFound       = errs.NotFoundError("webhook not found")

UnauthorizedError

Returned when authentication fails or token is invalid.

type UnauthorizedError string

const Unauthorized = UnauthorizedError("unauthorized")

Common Causes:

Missing authentication token
Invalid or expired token
Token doesn’t have required permissions

Specific Errors:

ErrUnauthorizedAgent          = errs.UnauthorizedError("permission denied")
ErrUnauthorizedIssue          = errs.UnauthorizedError("permission denied")
ErrUnauthorizedNetworkPolicy  = errs.UnauthorizedError("permission denied")
ErrUnauthorizedWebhookAccess  = errs.UnauthorizedError("permission denied for webhook access")
ErrUnauthorizedProjectSetting = errs.UnauthorizedError("permission denied for project setting")

PermissionDeniedError

Returned when user is authenticated but lacks necessary permissions.

type PermissionDeniedError string

const PermissionDenied = PermissionDeniedError("permission denied")

Common Causes:

User role doesn’t allow the operation
Resource belongs to different project
Attempting to modify system-level resources

ConflictError

Returned when operation conflicts with existing state.

type ConflictError string

const Conflict = ConflictError("resource already exists")

Common Causes:

Attempting to create duplicate resource
Resource already in desired state
Concurrent modification conflict

Specific Errors:

ErrNetworkPolicyAlreadyExists     = errs.ConflictError("network policy already exists")
ErrNetworkPolicyRuleAlreadyExists = errs.ConflictError("network policy rule already exists")
ErrProjectSettingAlreadyExists    = errs.ConflictError("project setting already exists")

InternalServerError

Returned when an unexpected server error occurs.

type InternalServerError string

const InternalServer = InternalServerError("internal server error")

Common Causes:

Database connection issues
Unexpected server state
Third-party service failures

Error Checking

Using errors.Is

Check error types using Go’s standard errors.Is:

import (
    "errors"
    "github.com/garnet-org/api/types/errs"
)

if errors.Is(err, errs.NotFound) {
    // Handle not found error
}

if errors.Is(err, errs.InvalidArgument) {
    // Handle invalid argument
}

if errors.Is(err, errs.Unauthorized) {
    // Handle authentication error
}

Checking Specific Errors

Check for specific error constants:

import (
    "errors"
    "github.com/garnet-org/api/types"
)

if errors.Is(err, types.ErrAgentNotFound) {
    // Agent doesn't exist
}

if errors.Is(err, types.ErrInvalidIssueState) {
    // Invalid issue state provided
}

Is Helper Function

Check if error is any Garnet API error:

if errs.Is(err) {
    // This is a known Garnet API error type
}

Domain-Specific Errors

Agent Errors

const (
    ErrUnauthorizedAgent = errs.UnauthorizedError("permission denied")
    ErrAgentNotFound     = errs.NotFoundError("agent not found")
    ErrInvalidAgentType  = errs.InvalidArgumentError("invalid agent kind")
)

Event Errors

const (
    ErrInvalidEventKind             = errs.InvalidArgumentError("invalid event kind")
    ErrIDcannotBeEmpty              = errs.InvalidArgumentError("id is required")
    ErrInvalidEventV2ID             = errs.InvalidArgumentError("v2 event id must be a valid UUID")
    ErrEventNotFound                = errs.NotFoundError("event not found")
    ErrEventHasNoNetworkDestination = errs.InvalidArgumentError("event has no network destination")
    ErrMetadataNameEmpty            = errs.InvalidArgumentError("metadataName cannot be empty")
    ErrMetadataNameTooLong          = errs.InvalidArgumentError("metadataName too long, maximum 64 characters allowed")
    ErrTooManyMetadataNames         = errs.InvalidArgumentError("too many metadata names, maximum 20 allowed")
)

Issue Errors

const (
    ErrInvalidIssueState            = errs.InvalidArgumentError("invalid issue state")
    ErrInvalidIssuePriority         = errs.InvalidArgumentError("invalid issue priority")
    ErrInvalidIssueClass            = errs.InvalidArgumentError("invalid issue class")
    ErrInvalidIssueDescription      = errs.InvalidArgumentError("invalid issue description")
    ErrInvalidIssueEventIDs         = errs.InvalidArgumentError("invalid issue event IDs")
    ErrInvalidIssueReason           = errs.InvalidArgumentError("invalid issue reason")
    ErrIssueHasNoNetworkDestination = errs.InvalidArgumentError("issue has no network destination")
    ErrUnauthorizedIssue            = errs.UnauthorizedError("permission denied")
    ErrNoAssociatedEvents           = errs.InvalidArgumentError("issue has no associated events")
)

Network Policy Errors

const (
    ErrInvalidNetworkPolicyScope         = errs.InvalidArgumentError("invalid network policy scope")
    ErrInvalidNetworkPolicyRepositoryID  = errs.InvalidArgumentError("invalid network policy repository id")
    ErrInvalidNetworkPolicyWorkflowName  = errs.InvalidArgumentError("invalid network policy workflow name")
    ErrInvalidNetworkPolicyClusterName   = errs.InvalidArgumentError("invalid network policy cluster name")
    ErrInvalidNetworkPolicyNodeName      = errs.InvalidArgumentError("invalid network policy node name")
    ErrInvalidNetworkPolicyRuleType      = errs.InvalidArgumentError("invalid network policy rule type")
    ErrInvalidNetworkPolicyRuleValue     = errs.InvalidArgumentError("invalid network policy rule value")
    ErrInvalidNetworkPolicyCIDRMode      = errs.InvalidArgumentError("invalid network policy CIDR mode")
    ErrInvalidNetworkPolicyResolveMode   = errs.InvalidArgumentError("invalid network policy resolve mode")
    ErrNetworkPolicyNotFound             = errs.NotFoundError("network policy not found")
    ErrNetworkPolicyRuleNotFound         = errs.NotFoundError("network policy rule not found")
    ErrNetworkPolicyAlreadyExists        = errs.ConflictError("network policy already exists")
    ErrNetworkPolicyRuleAlreadyExists    = errs.ConflictError("network policy rule already exists")
    ErrUnauthorizedNetworkPolicy         = errs.UnauthorizedError("permission denied")
)

Webhook Errors

const (
    ErrWebhookNotFound           = errs.NotFoundError("webhook not found")
    ErrUnauthorizedWebhookAccess = errs.UnauthorizedError("permission denied for webhook access")
    ErrWebHookInvalidKind        = errs.InvalidArgumentError("invalid webhook kind")
)

Project Setting Errors

const (
    ErrProjectSettingNotFound      = errs.NotFoundError("project setting not found")
    ErrInvalidProjectSettingKey    = errs.InvalidArgumentError("invalid project setting key")
    ErrInvalidProjectSettingValue  = errs.InvalidArgumentError("invalid project setting value")
    ErrUnauthorizedProjectSetting  = errs.UnauthorizedError("permission denied for project setting")
    ErrProjectSettingAlreadyExists = errs.ConflictError("project setting already exists")
)

Context Errors

const (
    ErrMissingKubernetesContext = errs.InvalidArgumentError("missing Kubernetes context")
    ErrMissingClusterName       = errs.InvalidArgumentError("missing cluster name")
    ErrMissingNodeName          = errs.InvalidArgumentError("missing node name")
    ErrMissingRepositoryID      = errs.InvalidArgumentError("missing repository ID in agent context")
    ErrMissingWorkflow          = errs.InvalidArgumentError("missing workflow in agent context")
    ErrMissingGitHubContext     = errs.InvalidArgumentError("agent does not have GitHub context")
)

Error Handling Best Practices

1. Always Check Errors

if err := agent.Validate(); err != nil {
    return nil, err
}

2. Use Type Checks for Different Handling

if errors.Is(err, errs.NotFound) {
    return nil, status.Error(codes.NotFound, err.Error())
}

if errors.Is(err, errs.InvalidArgument) {
    return nil, status.Error(codes.InvalidArgument, err.Error())
}

if errors.Is(err, errs.Unauthorized) {
    return nil, status.Error(codes.Unauthenticated, err.Error())
}

3. Provide Context

if err := policy.Validate(); err != nil {
    return fmt.Errorf("validating network policy: %w", err)
}

4. Check Specific Errors When Needed

if errors.Is(err, types.ErrNetworkPolicyAlreadyExists) {
    // Update existing policy instead of creating
    return client.UpdatePolicy(ctx, policy)
}

HTTP Status Code Mapping

Error Type	HTTP Status	Code
InvalidArgumentError	400	Bad Request
UnauthorizedError	401	Unauthorized
PermissionDeniedError	403	Forbidden
NotFoundError	404	Not Found
ConflictError	409	Conflict
InternalServerError	500	Internal Server Error

Core Types

Utility Types

Error Types

Overview

Error Types

InvalidArgumentError

NotFoundError

UnauthorizedError

PermissionDeniedError

ConflictError

InternalServerError

Error Checking

Using errors.Is

Checking Specific Errors

Is Helper Function

Domain-Specific Errors

Agent Errors

Event Errors

Issue Errors

Network Policy Errors

Webhook Errors

Project Setting Errors

Context Errors

Error Handling Best Practices

1. Always Check Errors

2. Use Type Checks for Different Handling

3. Provide Context

4. Check Specific Errors When Needed

HTTP Status Code Mapping

Build docs developers (and LLMs) love

Core Types

Utility Types

​Overview

​Error Types

​InvalidArgumentError

​NotFoundError

​UnauthorizedError

​PermissionDeniedError

​ConflictError

​InternalServerError

​Error Checking

​Using errors.Is

​Checking Specific Errors

​Is Helper Function

​Domain-Specific Errors

​Agent Errors

​Event Errors

​Issue Errors

​Network Policy Errors

​Webhook Errors

​Project Setting Errors

​Context Errors

​Error Handling Best Practices

​1. Always Check Errors

​2. Use Type Checks for Different Handling

​3. Provide Context

​4. Check Specific Errors When Needed

​HTTP Status Code Mapping

Build docs developers (and LLMs) love

Overview

Error Types

InvalidArgumentError

NotFoundError

UnauthorizedError

PermissionDeniedError

ConflictError

InternalServerError

Error Checking

Using errors.Is

Checking Specific Errors

Is Helper Function

Domain-Specific Errors

Agent Errors

Event Errors

Issue Errors

Network Policy Errors

Webhook Errors

Project Setting Errors

Context Errors

Error Handling Best Practices

1. Always Check Errors

2. Use Type Checks for Different Handling

3. Provide Context

4. Check Specific Errors When Needed

HTTP Status Code Mapping