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

Task	Method
Servers
List servers	client.Server.All(ctx)
Get server	client.Server.GetByID(ctx, 123) or GetByName(ctx, "web")
Create server	client.Server.Create(ctx, hcloud.ServerCreateOpts{})
Delete server	client.Server.Delete(ctx, server)
Reboot/Reset	client.Server.Reboot(ctx, server) / Reset(ctx, server)
Networks
Create network	client.Network.Create(ctx, hcloud.NetworkCreateOpts{})
Attach server	client.Server.AttachToNetwork(ctx, server, opts)
Volumes
Create volume	client.Volume.Create(ctx, hcloud.VolumeCreateOpts{})
Attach volume	client.Volume.Attach(ctx, volume, server)
Actions
Wait for action	client.Action.WaitFor(ctx, action)
Poll with callback	client.Action.WaitForFunc(ctx, callback, action)

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

Problem	Solution
Nil pointer panic	Always check error before using result
Action timeout	Use ctx, cancel := context.WithTimeout(...)
Missing pagination	Use client.Server.All(ctx) for complete list
Action failed	Check action error with WaitFor() return value
Rate limiting	SDK auto-retries, but add backoff for bulk ops