Quotas & Usage

# Quotas & Usage

Every Network Storage project runs on a package tier that defines monthly limits for API requests, bandwidth, and storage.

## Free Tier

| Resource | Limit |
|---|---|
| API Requests | 20,000,000 / month |
| Storage | 50 MB per project |
| Bandwidth | 100 GB / month |

The free tier is designed to handle most development and small-to-medium games comfortably. A game with 30 concurrent players sending requests every 5 seconds will use about 15.5 million requests per month, which is well within the limit.

Paid packages are coming soon for high-traffic games.

## What Counts as a Request

Every Network Storage operation counts as one request:

- `NetworkStorage.GetDocument(...)` calls
- `NetworkStorage.GetGameValues()` calls
- `NetworkStorage.CallEndpoint(...)` executions
- Sync Tool pull/push operations
- Ledger queries
- Rate limit status checks

Requests that fail authentication (HTTP 401) do **not** count toward your quota. Requests that are rate-limited (HTTP 429 from field rate limits) still count.

## What Happens When You Hit a Limit

The API returns HTTP `429` with error code `QUOTA_EXCEEDED`:

```yml
error:
  code: QUOTA_EXCEEDED
  message: Monthly API request limit reached (20,000,000).
```

The `message` field tells you which specific limit was reached (requests, bandwidth, or storage).

### Handling in Your Game

Check for `QUOTA_EXCEEDED` in your error handling. In C#:

```csharp
var result = await NetworkStorage.CallEndpoint( "save-progress", new
{
    checkpoint = "stage_3"
} );

if ( !result.HasValue )
{
    Log.Warning( "Network Storage request failed. Check logs for quota or service errors." );
    // Show a user-friendly message or disable repeated save attempts temporarily.
}
```

## Deployment Availability

The API uses zero-downtime blue/green deployments. During deployments:

- In-flight requests complete normally (up to 30 seconds)
- New requests receive `503 Service restarting` with `Retry-After: 3` header
- Deployments are managed via systemd with nginx reload for instant traffic switching
- Automatic rollback if health checks fail

Your game should handle `503` by waiting the `Retry-After` seconds and retrying. This is rare and brief.

## Checking Your Usage

### Dashboard

Visit your project's **Usage & Quotas** page to see:

- Current month usage vs limits with visual progress bars
- Previous month comparison
- Daily request breakdown
- Per-endpoint call counts and error rates
- Response time metrics (average, P95, P99)

Navigate to: **Network Storage > Your Project > Usage & Quotas**

### Quotas Reset

All quotas reset at the start of each calendar month (UTC midnight). There is no carry-over of unused quota.

## Bandwidth

Bandwidth is measured as the total bytes transferred in both directions:

- **Bytes in**: the size of data sent with endpoint calls, document writes, or sync operations
- **Bytes out**: the size of the response body (loaded data, endpoint results)

At 100 GB per month, you can transfer about 100 billion bytes. A typical player save is 1-5 KB, meaning you could load or save data tens of millions of times before hitting the bandwidth limit.

## Storage

Storage is the total size of all data stored for a project. This includes player saves, global collection records, and all associated metadata.

At 50 MB per project, you can store:

- ~50,000 player saves at 1 KB each
- ~10,000 player saves at 5 KB each
- Millions of rows across multiple game value tables

Storage usage is tracked cumulatively as data is written. Deleting records frees storage.

## Paid Packages

Paid packages are in development. They will offer higher limits for all resources. Join our [Discord](/discord) for updates on pricing and availability.