Sandbox Environment
Test your EventZR integration safely with sandbox keys, test credits, and simulated responses. No production data is affected.
1. What is the Sandbox?
The sandbox is an isolated testing environment that mirrors the production API. It allows you to develop and test your integration without processing real transactions, sending real notifications, or consuming production AI credits.
| Feature | Sandbox | Production |
|---|---|---|
| Base URL | sandbox.api.eventzr.com | api.eventzr.com |
| API Key Prefix | ez_test_ | ez_live_ |
| Data Persistence | Reset weekly (Sundays 00:00 UTC) | Permanent |
| Notifications | Logged only (no real delivery) | Real delivery (WhatsApp, email, SMS) |
| Payment Processing | Simulated (always succeeds) | Real transactions |
| AI Credits | 10,000 free test credits | Billed per usage |
| Rate Limits | 100 req/min | Tier-based (up to 10,000 req/min) |
2. Getting Sandbox Keys
Generate sandbox API keys from the Developer Console:
- Sign in to the Developer Console
- Navigate to Settings → API Keys
- Toggle the environment selector to Sandbox
- Click Generate Sandbox Key
# .env.local
EVENTZR_API_KEY=ez_test_your_sandbox_key_here
EVENTZR_BASE_URL=https://sandbox.api.eventzr.com
EVENTZR_TENANT_ID=00000000-0000-0000-0000-sandbox00001Configure the SDK to point at the sandbox by setting the baseUrl to the sandbox endpoint:
import { EventSvcClient } from '@eventzr/event-client';
const client = new EventSvcClient({
baseUrl: 'https://sandbox.api.eventzr.com/event/v1',
tenantId: process.env.EVENTZR_TENANT_ID,
headers: {
Authorization: `Bearer ${process.env.EVENTZR_API_KEY}`,
},
});3. Test Credits
Sandbox accounts receive 10,000 free AI credits that refresh automatically every week. These credits work identically to production credits but are never billed.
| Operation | Credits | Description |
|---|---|---|
| AI Chat Query | 5-10 | Single LLM completion |
| ZAR Ensemble | 60 | 3-model consensus response |
| Image Generation | 20-50 | AI image from text prompt |
| Profile Enrichment | 5 | AI-powered profile analysis |
| Video Generation | 100-500 | AI-generated video content |
// Check sandbox credit balance
const balance = await walletClient.wallets.getBalance();
console.log('Test credits remaining:', balance.credits);
// Output: Test credits remaining: 99404. Error Testing
The sandbox supports special trigger values that simulate error conditions. Use these to verify your error handling logic.
Trigger Error Responses
Pass specific values in the x-sandbox-error header to simulate failures:
| Header Value | HTTP Code | Simulates |
|---|---|---|
| rate_limit | 429 | Rate limit exceeded |
| insufficient_credits | 402 | Wallet balance too low |
| quota_exceeded | 403 | Monthly quota limit reached |
| server_error | 500 | Internal server error |
| timeout | 504 | Gateway timeout (30s delay) |
| maintenance | 503 | Service unavailable / maintenance |
Example: Testing Rate Limits
# Simulate a rate limit response
curl https://sandbox.api.eventzr.com/event/v1/events \
-H "Authorization: Bearer $EVENTZR_API_KEY" \
-H "x-tenant-id: 00000000-0000-0000-0000-sandbox00001" \
-H "x-sandbox-error: rate_limit"{
"error": {
"code": "ERR_RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Retry after 60 seconds.",
"http": 429
},
"meta": {
"request_id": "req_test_001",
"retry_after": 60
}
}Example: Testing Error Handling in Code
import { EventSvcClient } from '@eventzr/event-client';
const client = new EventSvcClient({
baseUrl: 'https://sandbox.api.eventzr.com/event/v1',
tenantId: '00000000-0000-0000-0000-sandbox00001',
headers: {
Authorization: `Bearer ${process.env.EVENTZR_API_KEY}`,
'x-sandbox-error': 'insufficient_credits',
},
});
try {
await client.events.create({
title: 'Test Event',
startDate: '2026-07-01T10:00:00Z',
endDate: '2026-07-01T18:00:00Z',
});
} catch (error) {
if (error.code === 'ERR_INSUFFICIENT_CREDITS') {
console.log('Handled: Insufficient credits');
// Show upgrade prompt to user
}
}5. Pre-Loaded Test Data
The sandbox comes with pre-seeded data you can use immediately without creating your own resources.
| Resource | Count | Notes |
|---|---|---|
| Events | 25 | Mix of draft, published, and cancelled |
| Venues | 10 | Various capacities and locations |
| Users | 50 | Roles: admin, organizer, attendee |
| Tickets | 200 | Multiple tiers (VIP, General, Early Bird) |
| Bookings | 75 | Various statuses and payment states |
6. Going to Production
When your integration is tested and ready, switching from sandbox to production requires minimal changes.
Migration Checklist
- 1Replace ez_test_ API key with ez_live_ production key
- 2Update base URL from sandbox.api.eventzr.com to api.eventzr.com
- 3Update tenant ID to your production tenant UUID
- 4Remove any x-sandbox-error headers from requests
- 5Verify webhook endpoints are publicly reachable
- 6Ensure sufficient AI credits in your production wallet
- 7Configure production CORS origins
- 8Enable production logging and monitoring
Environment Configuration
# Sandbox (.env.sandbox)
EVENTZR_API_KEY=ez_test_abc123
EVENTZR_BASE_URL=https://sandbox.api.eventzr.com
EVENTZR_TENANT_ID=00000000-0000-0000-0000-sandbox00001
# Production (.env.production)
EVENTZR_API_KEY=ez_live_xyz789
EVENTZR_BASE_URL=https://api.eventzr.com
EVENTZR_TENANT_ID=your-production-tenant-idImportant: Production API keys cannot be used against the sandbox endpoint, and sandbox keys cannot be used against the production endpoint. The API will return 401 Unauthorized if keys and endpoints are mismatched.
Related Guides
Questions about sandbox? The sandbox environment resets every Sunday at 00:00 UTC. If you need persistent test data, use the seed endpoints to recreate your test fixtures after each reset.