---
title: "Error Handling"
description: "Catch and inspect API errors, configure retries, and use idempotency keys in the PgBeam Go SDK."
canonical: "https://pgbeam.com/docs/go-sdk/error-handling"
last-updated: "2026-09-14T19:37:21.000Z"
---

# Error Handling

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

URL: https://pgbeam.com/docs/go-sdk/error-handling

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`.

## 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)`.

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

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

## 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.

## 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.