Skip to main content
A guardrail is set up once on the Guardrails screen and then attached to the keys it should govern. This page walks the screen. For what each rule does to a request, and the refusal a caller sees, read Guardrails first.

​
Before you start

You need to be the owner or an admin of the workspace. Every member can open the screen and read the guardrails that exist; the screen says so in its empty state:
Owners and admins set guardrails. Your keys run without caps until they do.
A guardrail governs keys, so have the key you want to govern created first. See Create an API key.

​
Create a guardrail

1

Open Guardrails

Sign in to the dashboard and open Guardrails in the sidebar, between Keys and BYOK. With nothing created yet the screen reads “Nothing’s fenced in yet” and points you at the create control, top right.
2

Name it

The name is how you will pick the guardrail out of a list and how a refusal names it to a developer, so make it say what it is for. Names are unique within a workspace, ignoring case, and are at most 120 characters.
3

Set a spend cap, or leave it off

Turn Spend cap on and enter an Amount in dollars, such as 100.00, and a Period of Daily, Weekly or Monthly. The amount is a whole number of cents above zero. With the cap off, the guardrail caps nothing, whatever the key’s own limit said: a guardrail replaces a key’s own limits while it is attached.
4

Choose the zero-data-retention setting

Under Privacy, pick Workspace default, On or Off. On routes the governed keys only to providers recorded as zero-data-retention. Off replaces the workspace setting with off for these keys. Workspace default inherits whatever the workspace has set. See Zero data retention.
5

Turn on sensitive-data detectors

Under Sensitive-data detection, switch on any of Email addresses, IP addresses and Passwords, secrets and API keys. A request whose prompt carries one of them is refused before it is sent. The screen says how much each rule adds to a request once it has measured it.
6

Create

Press Create guardrail. The guardrail appears as a card with its spend cap and ZDR choice on its first lines and nothing attached yet.
The form also lists Provider selection, Model selection, No training, Regions, Token limits and Injection checks under a “Coming soon” heading. Those rules are enforced when a guardrail carries them, and the screen cannot write them yet. See Guardrails for what each will do.

​
Attach it to a key

There are two ways in, and they do the same thing. From the guardrail. On the guardrail’s card, open Keys this guardrail governs and tick the keys. A tick that will not save says so: “The save did not finish, so the ticks above show where it stands.” From the key. On the Keys screen, each key you can see has a Guardrail cell reading “None” or the guardrail’s name. Open Attach to… and choose the guardrail. The cell is only offered to owners and admins. A key is governed by at most one guardrail. Attaching a second one is refused:
This key is already governed by guardrail NAME. Detach it from that one before attaching it here.
Once attached, the key’s own Edit limits control refuses to change its credit limit, naming the guardrail, until you detach it.

​
Edit or delete a guardrail

Edit on the card opens the same form. Saving replaces the whole guardrail, name included, and every attached key picks the change up before the save is reported done. Delete sits behind a confirm. A guardrail that still governs keys cannot be deleted. The refusal counts and names the keys:
Detach each key first, from either side, then delete.

​
What a developer sees when a rule trips

A refused request gets an error in the usual envelope with the guardrail’s name in the message and a code the client can branch on. Nothing is charged and no credit is held for it. The full code table is on Guardrails; the one everyone meets first is the spend cap, which answers HTTP 402 with the code key_limit_exceeded and a sentence ending in which guardrail set the cap. On the Activity screen the request lands as a refusal on the key’s line, so a cap that is tripping shows up where the spend would have.

​
Refusals you may hit on the screen

​
Next

Guardrails

Every rule, what it does to a request, and the codes a caller sees.

Create an API key

A key’s own expiry and credit limit, which a guardrail replaces while attached.
Every response carries the same id on two headers: x-hopscotch-request-id, which is ours, and x-request-id, which is the one the official OpenAI SDKs surface on their error objects. Every error envelope repeats it as request_id. Quote it when you ask us about a request. Without it we are guessing at which of your requests you mean.