Sandbox and Testing

Why a sandbox

A sandbox is an isolated copy of an API where you can experiment without consequences. Requests there do not move real money, contact real people, or alter real records. That freedom is essential: integration work involves mistakes, and you want them to happen somewhere harmless.

A sandbox lets you learn the API's shape, confirm your request and response handling, and rehearse edge cases. Because nothing is live, you can be deliberately reckless — send malformed data, trigger errors, hammer endpoints — to see how the system behaves. Treat the sandbox as your rehearsal stage and production as opening night. See the developer portal to get started.

Keep environments apart

The cardinal rule is strict separation between test and live. Use distinct credentials, distinct configuration, and ideally distinct code paths that cannot be confused at runtime.

• Separate keys — sandbox credentials must never reach production and vice versa.
• Label clearly — make it obvious in logs and config which environment is active.
• Fail safe — if the environment is ambiguous, refuse to run rather than guess.

A leaked or mixed-up credential is how test traffic ends up hitting live systems. Make the boundary explicit and hard to cross by accident. See environment configuration for how to wire this up.

Testing without live calls

Not every test should hit even the sandbox. Fast, reliable tests run locally against recorded or stubbed responses. Use these for the bulk of your suite, and reserve real sandbox calls for a smaller set of integration tests.

Mocking lets you assert how your code reacts to specific responses — including ones that are hard to provoke on demand, like a particular error or an empty list. A typical layered approach is unit tests with stubs, a handful of integration tests against the sandbox, and a smoke test before each release. This keeps the suite quick while still proving the wiring works against a real endpoint.

Rehearsing failure

Happy-path testing is not enough. Your integration must cope with timeouts, rate limits, validation errors and partial failures, and a sandbox is where you practise. Deliberately provoke these conditions and confirm your client responds correctly.

// pseudo-test
response = client.create(bad_payload)
assert response.status == 400
assert handler.was_not_retried()

Verify that retryable errors are retried, that client errors are not, and that failures are logged with enough context to diagnose. Walking through these scenarios in the sandbox means the first time you meet them in production is not a surprise. Failure handling that has never been exercised is failure handling you do not actually have.