Error Handling

Catch and inspect API errors, configure retries, and use idempotency keys in the PgBeam Go SDK.

All methods return an error on failure. Use pgbeam.IsNotFound() to check for 404 responses, and errors.As to extract detailed status information from *pgbeam.APIError.

import pgbeam "github.com/pgbeam/pgbeam-go"

project, err := client.Projects.Get(ctx, "proj_missing")
if err != nil {
    if pgbeam.IsNotFound(err) {
        fmt.Println("Project not found")
        return
    }

    var apiErr *pgbeam.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Error())
        return
    }

    log.Fatal(err)
}

APIError properties

Property	Type	Description
`StatusCode`	`int`	HTTP status code
`Status`	`string`	HTTP status text
`Body`	`string`	Raw response body

IsNotFound helper

pgbeam.IsNotFound(err) returns true if the underlying error is a 404 response. It uses errors.As internally, so it works even when the error is wrapped with fmt.Errorf("...: %w", err).

_, err := client.Projects.Get(ctx, "proj_missing")
if pgbeam.IsNotFound(err) {
    // Resource does not exist
}

See Response Conventions for the full list of error codes and the error envelope format.

Retries

The SDK automatically retries transient errors with exponential backoff. Non-retryable errors are returned immediately.

Retried: 408, 429, 502, 503, 504, and network errors (connection refused, DNS failure, timeout). All other status codes are not retried.

When the server returns a Retry-After header (on 429 or 503), the SDK uses that value instead of its own computed backoff.

See Response Conventions for the backoff formula and retry behavior details.

Retry configuration

import pgbeam "github.com/pgbeam/pgbeam-go"

client := pgbeam.NewClient(&pgbeam.ClientOptions{
    APIKey: "your-api-key",
    Retry: &pgbeam.RetryConfig{
        MaxRetries:   5,                       // default: 5 (0 to disable)
        InitialDelay: 500 * time.Millisecond,  // default: 500ms
        MaxDelay:     30 * time.Second,         // default: 30s
    },
})

Field	Type	Default	Description
`MaxRetries`	`int`	`5`	Max retry attempts after the initial request. `0` disables retries.
`InitialDelay`	`time.Duration`	`500ms`	Initial backoff delay.
`MaxDelay`	`time.Duration`	`30s`	Maximum backoff delay.

Disabling retries

client := pgbeam.NewClient(&pgbeam.ClientOptions{
    APIKey: "your-api-key",
    Retry:  &pgbeam.RetryConfig{MaxRetries: 0},
})

Context cancellation

Retry loops respect context.Context. If the context is cancelled or its deadline expires, the SDK stops retrying and returns the context error.

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

project, err := client.Projects.Get(ctx, "proj_abc123")

Idempotency

POST and PATCH requests automatically include an Idempotency-Key header when retries are enabled, so retries never double-create resources. The server caches responses for 24 hours.

See Response Conventions for how idempotency keys work.