Go SDK errors

The Go SDK splits outcomes into decisions and errors, and the split is load-bearing.

Decisions are values. An unsigned request, a bad signature, a buyer who cannot pay: these are expected events on a public endpoint, not faults in your program. They come back as results (VerifyResult, GuardResult, AllowanceDecision) carrying the ready-to-return Response. Nothing to catch, nothing to recover.
Errors are reserved for what you got wrong (malformed input, bad configuration) and what the environment did (the ZeroClick API unreachable or answering nonsense). They are *sellers.Error values with a stable machine-readable code.

This page covers the error side; the decision flow is on the API reference.

The Error type

type Error struct {
	Code      ErrorCode // stable classification; switch on this, not the message
	Operation string    // the SDK call that failed: "new", "guard", "guard_identity",
	                    // "check_allowance", "report_usage"
	Status    int       // HTTP status from the ZeroClick API, or 0 if no response arrived
	Reason    string    // the API's own denial code, when it gave one
	Cause     error     // the underlying transport or decoding failure, if any
}

func (e *Error) Error() string
func (e *Error) Unwrap() error

The message renders every populated field, for example:

zeroclick: api_status_error during report_usage (status 402) (reason usage_exhausted)

Unwrap returns Cause, so errors.Is and errors.As see through to the underlying failure.

Error codes

The core package defines four codes:

Code	Meaning
`malformed_input`	You handed the SDK something invalid: a config `New` refuses, a usage list with a duplicate meter or with both `Quantity` and `MaxQuantity` set, a missing service slug or idempotency key. `Cause` explains what.
`api_transport_error`	The call to the ZeroClick API never completed: timeout, DNS failure, connection refused, cancelled context. `Cause` holds the transport error.
`api_status_error`	The API answered with a 4xx or 5xx. `Status` holds the code. For usage reports refused with `402`, `404`, or `409`, `Reason` carries the API’s machine code: `402` for `access_inactive`, `plan_expired`, or `usage_exhausted`; `409` for `meter_not_priced`; otherwise `404`.
`api_response_invalid`	The API answered, but with a body the SDK could not read as the documented shape: unparseable JSON, a missing field, an unrecognized error code on a typed status.

See errors for the control-plane error envelope these map from.

jwe error codes

The jwe subpackage (encrypted request bodies) adds its own codes, on the same *sellers.Error type with Operation set to decrypt_request or encrypt_response:

Code	Meaning
`invalid_compact_jwe`	The body is not a well-formed five-segment Compact JWE: wrong segment count, an empty segment, an undecodable protected header, or a parse failure.
`unsupported_jwe_suite`	The header names an algorithm outside the pinned suite (ECDH-ES+A256KW key management, A256GCM content encryption).
`jwe_kid_required`	The protected header carries no `kid`, so no private key can be selected.
`invalid_reply_jwk`	The buyer’s reply key is malformed: not an EC P-256 public key, unexpected members, or bad coordinates.
`private_reply_jwk`	The reply key carries private key material. A protocol violation, refused outright rather than quietly used.
`private_key_not_found`	Your resolver does not know the header’s `kid`. `Reason` carries the kid.
`private_key_resolution_failed`	The private-key lookup itself failed: a vault error, not a missing key. `Reason` carries the kid.
`decryption_failed`	The suite and key were right, but decryption failed. `Reason` carries the kid. Also returned for an encrypted request whose plaintext is empty, a known Go JOSE-library limitation; see the API reference.
`encryption_failed`	Encrypting the reply to the buyer’s key failed.

The SDK reports a nil private-key resolver as the core malformed_input.

Verification refusals are decisions, not errors

When a signature does not verify, Verify and Guard return a deny decision, not an error. Reason carries a FailureReason value saying why:

Reason	The request was refused because
`missing_signature`	No `zc-signature` header at all, which is typical for traffic that did not come through ZeroClick.
`malformed_signature`	The header does not parse as `t=…,kid=…,v1=…`: a missing or duplicate member, a malformed timestamp, or a value that is not 64 lowercase hex characters.
`stale_timestamp`	The signature’s timestamp drifted more than `ToleranceSeconds` (default 300) from your clock, in either direction.
`missing_request_id`	The `zc-request-id` header is absent.
`unknown_kid`	Your secrets hold no entry for the signature’s key id: commonly a secret rotated away too early, or an environment mismatch.
`invalid_signature`	The HMAC did not match: the body, path, method, or ids differ from what ZeroClick signed, or the secret is wrong. A proxy that rewrites the raw request target is a common cause; see Go SDK middleware.

Every one of these surfaces to the caller as the same 401 {"error":"invalid_zeroclick_signature"} response. The body deliberately says nothing about why. The specific reason rides on VerifyResult.Reason and GuardResult.Reason for your logs. One verification path does produce an error rather than a refusal: a signing-secret resolver fault. If your Resolve function fails (a vault unreachable) or resolves an empty secret, Verify returns an error wrapping ErrSecretResolution. An infrastructure fault must not be silently read as a forged request:

var ErrSecretResolution = errors.New("zeroclick: signing secret could not be resolved")

Test for it with errors.Is(err, sellers.ErrSecretResolution). An unknown kid, by contrast, is an ordinary unknown_kid refusal.

Allowance denials are decisions too

allowed: false from the allowance API is always a 402 decision, never an error: Guard returns a deny result carrying the priced payment_required response, with Reason set to the denial code. The SDK exports the codes as the Denial* constants: service_not_found, access_not_found, access_inactive, plan_expired, meter_not_found, meter_not_priced, usage_exhausted. See usage and allowances for what each means. The SDK still honors a denial whose reason it does not recognize: the decision stands, and the unfamiliar reason passes through for you to log.

Outage classification

IsAllowanceUnavailable answers one question: did the allowance API give no answer? Only that condition is subject to the configured outage Policy (see configuration). Everything else fails loudly, because conflating the cases all failed in the same direction: serving unbilled work.

func IsAllowanceUnavailable(err error) bool

Condition	Classification
Timeout, DNS failure, connection refused (`api_transport_error`)	No answer; the policy applies.
`5xx`, `429`, or `408` from the API (`api_status_error`)	No answer: transient, genuinely worth failing open on. The policy applies.
A response the SDK cannot read (`api_response_invalid`)	No answer: an answer that cannot be understood is no answer. The policy applies.
Any other `4xx` (`api_status_error`): a revoked or wrong-environment API key, a suspended account, an unknown service	Always an error. Permanent, never self-heals, and every second of failing open makes the loss larger.
`malformed_input`	Always an error. Your bug, not an outage.
A cancelled context (`errors.Is(err, context.Canceled)`, at any depth)	Not an outage. The caller went away; authorizing work because nobody is listening is backwards. `Guard` runs the check on its own timeout regardless, so its real answer stands.

A readable decision with an unfamiliar reason never reaches this classification at all: the SDK honors it as a 402, per the previous section. The guard consults the policy only after a signature verifies, so a fail-open allowance policy never becomes a fail-open signature policy.

Patterns

Inspect any SDK error by code:

var zcErr *sellers.Error
if errors.As(err, &zcErr) {
	log.Printf("zeroclick %s failed: code=%s status=%d reason=%s",
		zcErr.Operation, zcErr.Code, zcErr.Status, zcErr.Reason)
}

Unwrap lets errors.Is reach the cause:

if errors.Is(err, context.DeadlineExceeded) {
	// The check timeout (default 1.5 s) elapsed.
}
if errors.Is(err, sellers.ErrSecretResolution) {
	// The signing-secret lookup failed: alert on infrastructure, not on buyers.
}

When you drive the check yourself, classify before deciding. This is exactly what Guard does internally with Config.Policy:

decision, err := seller.CheckAllowance(ctx, zc.RequestID, "product-watch",
	[]sellers.UsageItem{{MeterSlug: "requests", Quantity: 1}})
switch {
case err == nil:
	// A real answer: decision.Allowed, decision.Reason.
case sellers.IsAllowanceUnavailable(err):
	// No answer. Apply your own outage policy.
default:
	// Misconfiguration or a permanent API refusal. Fix it; do not fail open.
	log.Printf("allowance check broken: %v", err)
}

A failed ReportUsage deserves the same care in the other direction: the buyer already has their result. Log the error with its Reason, and retry later with the same derived idempotency key rather than failing the delivered request. A replay is a harmless Duplicate: true. See settle usage.

Overview

TypeScript

Python

Go

The Error type

Error codes

jwe error codes

Verification refusals are decisions, not errors

Allowance denials are decisions too

Outage classification

Patterns

​The Error type

​Error codes

​jwe error codes

​Verification refusals are decisions, not errors

​Allowance denials are decisions too

​Outage classification

​Patterns

The Error type

Error codes

jwe error codes

Verification refusals are decisions, not errors

Allowance denials are decisions too

Outage classification

Patterns