Hetzner Cloud Go SDK

Overview

The official Go SDK for Hetzner Cloud provides type-safe access to 23+ resource types with automatic retries, action polling, and comprehensive error handling. Use it for bots, automation, integrations, and complex workflows. For quick CLI operations, use hetzner:hcloud-cli instead.

Quick Setup

import "github.com/hetznercloud/hcloud-go/v2/hcloud"

// Create client
client := hcloud.NewClient(hcloud.WithToken("your-api-token"))

go get github.com/hetznercloud/hcloud-go/v2/hcloud

Quick Reference

API Categories

See references/api-reference.md for complete method list:

• Servers (create, lifecycle, networking)
• Networks, subnets, routes
• Volumes
• Firewalls and rules
• Load balancers, targets, services
• Floating IPs, Primary IPs
• SSH keys, images, certificates
• DNS zones (GA in v2.30.0)
• Storage boxes (experimental)

Client Configuration

client := hcloud.NewClient(
    hcloud.WithToken("token"),                    // Required
    hcloud.WithEndpoint("https://api.hetzner.cloud/v1"), // Custom endpoint
    hcloud.WithApplication("myapp", "1.0.0"),     // User-Agent
    hcloud.WithDebugWriter(os.Stderr),            // Debug logging
    hcloud.WithHTTPClient(customClient),          // Custom HTTP client
    hcloud.WithRetryOpts(hcloud.RetryOpts{        // Retry config
        MaxRetries: 5,
        BackoffFunc: hcloud.ExponentialBackoff(2, time.Second),
    }),
    hcloud.WithPollOpts(hcloud.PollOpts{          // Action polling
        BackoffFunc: hcloud.ConstantBackoff(500 * time.Millisecond),
    }),
)

Common Patterns

See references/patterns.md for idiomatic patterns:

• Error handling
• Action polling
• Pagination
• Resource lookups

Action Handling

All long-running operations return an Action:

result, _, err := client.Server.Create(ctx, opts)
if err != nil {
    return err
}

// Wait for completion
if err := client.Action.WaitFor(ctx, result.Action); err != nil {
    return err
}

// Or with progress callback
err = client.Action.WaitForFunc(ctx,
    func(update *hcloud.Action) error {
        fmt.Printf("Progress: %.0f%%\n", update.Progress)
        return nil
    },
    result.Action,
)

Error Handling

import "github.com/hetznercloud/hcloud-go/v2/hcloud"

err := someAPICall()

// Check specific error codes
if hcloud.IsError(err, hcloud.ErrorCodeNotFound) {
    // Resource doesn't exist
}

// Get error details
if apiErr, ok := err.(*hcloud.APIError); ok {
    fmt.Printf("Error: %s - %s\n", apiErr.Code, apiErr.Message)
}

Common error codes:

• ErrorCodeNotFound - Resource doesn't exist
• ErrorCodeInvalidInput - Validation error
• ErrorCodeForbidden - Insufficient permissions
• ErrorCodeRateLimitExceeded - Rate limit hit (auto-retried)
• ErrorCodeConflict - Resource changed (auto-retried)
• ErrorCodeLocked - Another action running

Common Mistakes