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.
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | Bad arguments. |
| 401 | INVALID_SECRET_KEY | The key is missing, wrong, revoked, or its owner or workspace is not active. |
| 403 | INSUFFICIENT_SCOPE | The key does not have ai:chat. |
| 403 | TENANT_MISMATCH, ORG_MISMATCH | A header disagrees with the key. The SDKs never send one. |
| 403 | FEATURE_DISABLED, CLIENT_TYPE_DISABLED | The workspace does not allow this use of the key. Contact us to enable it. |
| 404 | NOT_FOUND | No such conversation for this key. |
| 429 | RATE_LIMITED | Too many requests. Retry-After says how long to wait. |
| 429 | RUN_LIMIT_REACHED | The workspace's Safeguard AI run capacity is in use. Retry-After is short. |
| 502 | UPSTREAM_ERROR | The service could not complete the turn. |
| 503 | AUTH_UNAVAILABLE | Key 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,streamand create: on 429 or 503 that carriesRetry-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 withretryAfterset. - Never a
queryorstreamthat 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.