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

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

client.Server.All(ctx)

client.Server.GetByID(ctx, 123)

GetByName(ctx, "web")

client.Server.Create(ctx, hcloud.ServerCreateOpts{})

client.Server.Delete(ctx, server)

client.Server.Reboot(ctx, server)

Reset(ctx, server)

client.Network.Create(ctx, hcloud.NetworkCreateOpts{})

client.Server.AttachToNetwork(ctx, server, opts)

client.Volume.Create(ctx, hcloud.VolumeCreateOpts{})

client.Volume.Attach(ctx, volume, server)

client.Action.WaitFor(ctx, action)

client.Action.WaitForFunc(ctx, callback, action)

API Categories

See

references/api-reference.md

• 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

• 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

ctx, cancel := context.WithTimeout(...)

client.Server.All(ctx)

WaitFor()