Safeguard Docs
Safeguard AI SDKs

Errors and retries

The error types the Safeguard AI SDKs raise, the API error codes, and exactly when the SDKs retry.

Errors and retries

Every failure is a typed error with the HTTP status, the API code, a message, the Retry-After seconds when the server sent one, and the server's request_id. Quote the request id to support.

StatusCodeMeaning
400INVALID_REQUESTBad arguments.
401INVALID_SECRET_KEYThe key is missing, wrong, revoked, or its owner or workspace is not active.
403INSUFFICIENT_SCOPEThe key does not have ai:chat.
403TENANT_MISMATCH, ORG_MISMATCHA header disagrees with the key. The SDKs never send one.
403FEATURE_DISABLED, CLIENT_TYPE_DISABLEDThe workspace does not allow this use of the key. Contact us to enable it.
404NOT_FOUNDNo such conversation for this key.
429RATE_LIMITEDToo many requests. Retry-After says how long to wait.
429RUN_LIMIT_REACHEDThe workspace's Safeguard AI run capacity is in use. Retry-After is short.
502UPSTREAM_ERRORThe service could not complete the turn.
503AUTH_UNAVAILABLEKey checking is briefly unavailable. Retry.

The SDKs add client codes: TIMEOUT, NETWORK_ERROR, INVALID_RESPONSE, STREAM_INCOMPLETE and MISSING_API_KEY.

Handling errors

The program below sends a key that does not exist, so it shows a real 401, and includes a wait-and-retry helper for 429.

TypeScript

import { Safeguard, SafeguardError } from "@safeguard-sh/sdk";

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function ask(client, prompt) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await client.query(prompt);
    } catch (e) {
      if (!(e instanceof SafeguardError)) throw e;
      // The SDK already retried a 429 that carried Retry-After. If it still got through, wait and try again.
      if (e.status === 429 && attempt < 2) {
        await sleep((e.retryAfter ?? 5) * 1000);
        continue;
      }
      throw e;
    }
  }
}

// A key that does not exist is refused with 401 INVALID_SECRET_KEY.
const bad = new Safeguard({ apiKey: "sg_sk_this_key_does_not_exist", maxRetries: 0 });
try {
  await ask(bad, "hello");
} catch (e) {
  if (e instanceof SafeguardError) {
    console.log(e.status, e.code, e.message, e.retryAfter, e.requestId !== null);
  } else {
    throw e;
  }
}

Python

import time

from safeguard_sdk import RateLimitError, Safeguard, SafeguardError


def ask(client: Safeguard, prompt: str):
    for attempt in range(3):
        try:
            return client.query(prompt)
        except RateLimitError as e:
            # The SDK already retried a 429 that carried Retry-After. If it still got through, wait and try again.
            if attempt == 2:
                raise
            time.sleep(e.retry_after or 5)


# A key that does not exist is refused with 401 INVALID_SECRET_KEY (AuthenticationError).
bad = Safeguard(api_key="sg_sk_this_key_does_not_exist", max_retries=0)
try:
    ask(bad, "hello")
except SafeguardError as e:
    print(type(e).__name__, e.status, e.code, e.message, e.retry_after, e.request_id is not None)

Python raises AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), RateLimitError (429, with retry_after), APIError (5xx) and APIConnectionError (no response; APITimeoutError for a timeout). All are SafeguardError; other 4xx raise SafeguardError itself.

Go

package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	safeguard "safeguard.sh/sdk"
)

// ask retries a rate-limited query. The SDK already retried a 429 that carried a short Retry-After;
// this handles one that still got through.
func ask(ctx context.Context, c *safeguard.Client, prompt string) (*safeguard.QueryResult, error) {
	for attempt := 0; ; attempt++ {
		res, err := c.Query(ctx, prompt, nil)
		var apiErr *safeguard.APIError
		if errors.As(err, &apiErr) && errors.Is(err, safeguard.ErrRateLimited) && attempt < 2 {
			wait := apiErr.RetryAfter
			if wait <= 0 {
				wait = 5 * time.Second
			}
			select {
			case <-time.After(wait):
				continue
			case <-ctx.Done():
				return nil, ctx.Err()
			}
		}
		return res, err
	}
}

func main() {
	// A key that does not exist is refused with 401 INVALID_SECRET_KEY.
	bad, _ := safeguard.NewClient(safeguard.WithAPIKey("sg_sk_this_key_does_not_exist"), safeguard.WithMaxRetries(0))
	_, err := ask(context.Background(), bad, "hello")

	var apiErr *safeguard.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.Status, apiErr.Code, apiErr.Message, apiErr.RetryAfter, apiErr.RequestID != "")
	}
	fmt.Println(errors.Is(err, safeguard.ErrUnauthorized))
}

Go returns an *APIError for any non-2xx answer, which matches the sentinels ErrInvalidRequest, ErrUnauthorized, ErrForbidden, ErrInsufficientScope, ErrNotFound, ErrRateLimited, ErrRunLimit, ErrUpstream, ErrUnavailable and ErrServer through errors.Is. A transport failure is a *ConnError.

Example output of each program (the TypeScript and Python programs print the same fields; Go adds the sentinel check):

401 INVALID_SECRET_KEY Provide a valid Safeguard API key as 'Authorization: Bearer <key>'. ...

Retries

The SDKs retry only when repeating cannot do the work twice, up to maxRetries times (default 2) with exponential backoff:

  • GET calls (context, list, get, messages): on network errors and timeouts, and on 429, 502, 503 and 504.
  • Any call, including query, stream and create: on 429 or 503 that carries Retry-After, because the service refused the request before starting it. The SDK waits for the header's value. A wait longer than the SDK's limit (60 seconds in TypeScript and Python, 30 in Go) is not taken: the error is thrown with retryAfter set.
  • Never a query or stream that the service has started, and never a POST after a network error or timeout. The answer may already be running, so the error is raised and you decide.

Set maxRetries to 0 to turn retries off.

On this page