# Sandbox

> What Sandbox actually does: the same engine and contract as Production, free, bounded by a lifetime allowance of 2,000 units per organisation.

Sandbox is the environment in which you integrate the API before Production. It serves the same API surface as Production, on the same URL: the key decides the environment. Sandbox calls go through the same resolution engine; what changes is billing, the allowance and the rate limits.

## What is identical to Production

- The three routes, the same fields, the same headers and the same error codes.
- The same engine and the same resolution policy: a descriptor resolved in Sandbox is resolved by the same computation as in Production.
- The same idempotency, deduplication, validation and retention rules.

## What differs

| | Sandbox | Production |
|---|---|---|
| Key prefix | `nry_mer_sbx_` | `nry_mer_live_` |
| Billing | None: `usage.billable` is always `false` | EUR 0.005 per successful enrichment, excluding taxes |
| Bound | Lifetime allowance of 2,000 units per organisation | No allowance |
| Rate | Burst of 60 requests, 5 requests per second, per key | Not published: read `Noryo-RateLimit-Limit` |
| Access | Keys created in Platform | After Noryo has reviewed an application |

## The 2,000-unit allowance

Sandbox carries a **lifetime allowance of 2,000 units per organisation**, not per month and not per key: every Sandbox key of every workspace in one organisation draws from the same allowance. It is set when the organisation is created.

A call consumes the units its result carries, the ones the response announces in `usage.units`:

| Result | Units consumed |
|---|---|
| `resolved` | 1 |
| `refresh_recalculated` | 1 |
| `partial`, `not_found` | 0 |
| Idempotent replay, replay by `external_transaction_id` | 0 |
| Error (`4xx`, `5xx`) | 0 |

Once the allowance is exhausted, a call that would have consumed a unit is refused:

```json
{
  "type": "https://developer.noryo.app/errors/sandbox_quota_exhausted",
  "title": "Sandbox quota exhausted",
  "status": 402,
  "code": "sandbox_quota_exhausted",
  "detail": "The organization has used its Sandbox allowance. Move to Production to continue.",
  "request_id": "req_…"
}
```

Retrying the same request does not help: the allowance does not refill. See [sandbox_quota_exhausted](https://developer.noryo.app/en-GB/errors/sandbox_quota_exhausted).

> **Warning** Every create call must carry an `Idempotency-Key` or an `external_transaction_id`. Without them, two identical calls would consume the allowance twice; that is one reason why the API refuses them. See [The two identifiers](https://developer.noryo.app/en-GB/merchant/identifiers).

## Two separate worlds

Sandbox and Production share nothing: separate keys, separate rate-limit buckets, separate counters. An `enrichment_id` created in Sandbox cannot be read with a Production key (and the other way round): the read returns `404`. Idempotency keys and `external_transaction_id` values are also scoped to each environment. A Sandbox call can never bill a Production account. See [Environments](https://developer.noryo.app/en-GB/merchant/authentication/environments).

## Getting a Sandbox key

Sandbox keys are created on the [API keys](https://platform.noryo.app/keys) page of Platform. Until Noryo has opened Sandbox key issuance, creation is refused with the message `Sandbox access is not enabled yet.`. See [API keys](https://developer.noryo.app/en-GB/merchant/authentication/api-keys).

---

Canonical page: https://developer.noryo.app/en-GB/merchant/sandbox