Troubleshooting

Fix the common inference API errors: 401, 402, 403, 404, 429 and 5xx responses, a model that is not available, and a revoked key.

Every error from the inference API comes back in OpenAI's error shape. Read error.code first, because it says more than the HTTP status does.

{
  "error": {
    "message": "Invalid, revoked or expired API key. Keys start with sg-api- and are sent as 'Authorization: Bearer <key>'.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

A request refused before the gateway calls a provider costs nothing and does not appear in the request log. That covers every 401, 402, 403, 404 and 503 on this page, a 429 rate_limited, and most 400s. The full list of codes is in Errors.

401 invalid_api_key

The key is missing, malformed, unknown, revoked or expired, or its owner is no longer an active member. The gateway gives the same answer in every case.

Check the header. It must be Authorization: Bearer followed by the whole key: sg-api- and 64 lowercase hexadecimal characters. The Console's key list shows a masked form, which is not the key.
Check the kind of key. Only inference keys work here. MCP keys, Guard SDK keys and Safeguard sign-in tokens get this 401.
Was the key revoked? A revoked key is listed under Revoked on API keys. Create a new one.
Has its owner left? A key acts for the member who created it. When that member is deactivated or removed, the key stops working. Create a new key while signed in as an active member.
Keys created in the Console never expire, so an old key that stopped working was revoked, or its owner can no longer use it.

402 credit or a spend limit

`code`	Fix
`insufficient_credit`	Add credit, or lower `max_tokens` so the request's hold fits. At a balance of zero or less, every request is refused.
`key_spend_limit_exceeded`	The key's owner raises or clears the key's monthly limit, or you use another key.
`account_spend_limit_exceeded`	A tenant admin or super admin raises or clears the workspace's monthly limit.

The checks use the most a request could cost, so a request with a large max_tokens can be refused while some credit is left. See Spend controls.

403 gateway_disabled

The message is "The Safeguard inference API is not enabled for this account." The API is in early access: it is deployed but switched off, and Safeguard switches it on per workspace. Ask Safeguard to turn it on for yours.

In the Console it looks like this:

Before the API is on for your workspace, Create key on API keys is greyed out, and a Workbench run says "The inference endpoint is not connected yet."
When your workspace is on but the gateway as a whole is still switched off, Console pages say "The inference gateway is not connected for this workspace yet." with the reason underneath.

404 model_not_found

The message is "Model not found:" followed by the id you sent. That id is not in Safeguard's model catalog. Ids must match exactly, including case. List the ids you can use, and copy one:

curl https://api.safeguard.sh/gpt/v1/models \
  -H "Authorization: Bearer $SAFEGUARD_INFERENCE_KEY"

Model not available

A 503 model_unavailable means the model is in the catalog but cannot be used right now. The end of the message says why:

Message ends with	Meaning	Fix
"it is not available through the API yet"	The model has not been made available through the API, or its provider is not set up yet.	Pick a model from `GET /gpt/v1/models`. Without `?all=true`, that list holds only models that are available through the API now.
"zero data retention is not offered for it"	Your workspace requires zero data retention, or the request set `provider.zdr`, and the model does not offer it.	Pick a model with `zdr_available: true`, or ask a tenant admin or super admin to turn off Only use models whose provider offers zero data retention.

If the message is "The model catalogue is temporarily unavailable; try again shortly.", retry with backoff.

In the Workbench picker, models marked (Request access) or (Coming soon) cannot be run.

429 too many requests

`code`	Meaning	Fix
`rate_limited`	Your key sent more requests in the last minute than its limit allows.	Wait the number of seconds in `Retry-After`. Spread requests out, or raise the key's Requests per minute with Edit on API keys, up to 10,000. Separate workloads can use separate keys.
`upstream_rate_limited`	The provider is rate limiting the gateway.	Wait for `Retry-After`, which is 5 seconds, and back off if it repeats. Turn on retries and fallbacks, or try another model.

5xx errors

Status and `code`	Meaning	Fix
500 `internal_error`	The gateway failed unexpectedly.	Retry once or twice with backoff. If it keeps happening, contact support.
502 `upstream_error`	The provider returned an error or could not be reached.	Retry with backoff, or turn on retries and fallbacks.
502 `upstream_auth`	The provider refused Safeguard's credentials.	Nothing to change on your side. Use another model, and tell Safeguard.
503 `auth_unavailable`	API keys cannot be checked right now.	Retry with backoff.
503 `billing_unavailable`	Credit cannot be checked right now.	Retry with backoff.
503 `model_unavailable`	See Model not available.
504 `upstream_timeout`	The provider did not answer in time.	Retry, lower `max_tokens`, or stream the response.

How to retry well is covered in Reliability and fallbacks.

A revoked key still works, or a key stopped working

It still works right after you revoked it. Revoking takes effect within 30 seconds. A request that started before then runs to its end.
It stopped working and nobody revoked it. Its owner was probably deactivated or removed from the workspace, which stops their keys. Create a new key.

A streamed answer stops with an error

If the provider fails after streaming has started, the stream ends with an error event and then data: [DONE]. The answer is incomplete, and the tokens produced so far are charged. Retry the request. See Streams that fail partway.

400 bad request

`code`	Usual cause
`invalid_request`	A field is missing or out of range, and `param` names it. For example, `temperature` must be from 0 to 2, `top_p` from 0 to 1, and `stop` can hold at most four strings.
`unsupported_parameter`	Something the API does not accept, such as image content, or `n` set to anything but 1.
`upstream_rejected`	The provider refused the request with a 400, 404, 413 or 422. Check the request against the model's limits, such as its context length. The gateway never retries it.

A body over 8 MiB gets 413 request_too_large. The field rules are in Chat completions.

Contact support

Write to hi@safeguard.sh with:

the response's id, which starts with gen-, if you got one;
the X-Generation-Id response header, which holds the same id;
the time of the request, the model and the error code;
the key's name or masked form. Never send the key itself.

Troubleshooting

On this page