Advanced

Troubleshooting

Common issues and how to resolve them. If your question is not answered here, open an issue on GitHub.

Getting 401 Unauthorized

This means Ghostbox could not validate your API key. Check the following:

  • Your key starts with sandbox_test_. Keys without this prefix are rejected.
  • For Bearer auth (Stripe, Resend, PostHog), the header must be Authorization: Bearer sandbox_test_....
  • For Basic auth (Mailchimp), use Authorization: Basic base64(anyuser:sandbox_test_...).
  • The key has not been deleted from the dashboard.
Verify your key worksbash
# Quick test with curl
curl -s https://ghostbox.dev/sandbox/stripe/v1/customers \
  -H "Authorization: Bearer sandbox_test_YOUR_KEY"

# Should return a JSON response, not 401

Getting 501 Not Implemented

This means the endpoint you are calling exists in the real API but has not been implemented in the Ghostbox sandbox yet. Built-in sandboxes cover the most commonly used endpoints. If you need an endpoint that returns 501, please open an issue requesting it.

Data from another test leaking into my test

State is isolated per API key per service. If you are seeing data you did not create, check:

  • You are not sharing the same API key across test suites that expect clean state. Create a separate key per test environment.
  • Previous test runs with the same key left residual data. Delete and recreate the key from the dashboard for a clean slate.
  • Your tests are running in parallel but sharing a key. Use separate keys for parallel test workers.

Sandbox responds slowly on first request

The first request to a service sandbox may take longer (1-3 seconds) because the sandbox runtime initializes the service definition and connects to the state store. Subsequent requests to the same service are fast (typically under 100ms). This is normal behavior and only affects the first request after a cold start.

Getting quota_exceeded error

The free tier allows 1,000 requests per month across all services. When you exceed this limit, you will receive:

json
{
  "sandbox_error": "quota_exceeded",
  "message": "Free tier limit exceeded. Upgrade to Pro for unlimited requests.",
  "timestamp": "2026-03-28T12:00:00Z"
}

Generation pipeline is stuck

If a sandbox generation job appears stuck, check the following:

  • Check the job status with ghostbox status. Generation typically takes 3-5 minutes.
  • If the docs URL requires authentication or is behind a paywall, the scraper cannot access it. Use a publicly accessible documentation URL.
  • If the pipeline is iterating on test failures, it may take longer. The pipeline retries up to 3 times before marking the job as failed.
  • If the job has been running for more than 10 minutes, try submitting again with ghostbox add <name> --docs-url <url> --force.

Content-Type mismatch errors

Each sandbox expects the same content type as the real API:

  • Stripe: application/x-www-form-urlencoded
  • Resend, PostHog, Mailchimp: application/json

If you send JSON to the Stripe sandbox or form-encoded data to Resend, the request body will not be parsed correctly.

CORS errors in the browser

Ghostbox sandbox endpoints are designed for server-to-server use (backend code, test suites, CI/CD). Calling sandbox URLs directly from browser JavaScript will likely hit CORS restrictions. If you need browser-side testing, proxy the requests through your own backend or use a test framework like Playwright that runs requests from Node.js.

Still stuck?

Open an issue on GitHub or reach out on Discord. Include the service name, endpoint, request body, and the full error response.

Open GitHub IssueBack to Docs