Rate Limits

Spekra applies rate limits to protect the platform and ensure fair usage for all users. This page documents the limits that apply to SDK report uploads.

SDK Report Uploads

When using @spekra/playwright, @spekra/jest, or other Spekra reporters, the following rate limits apply:

These limits are designed to be generous for typical CI usage. Most organizations will never hit these limits.

When You Might Hit Limits

You may approach rate limits if you:

• Run many test suites in parallel across multiple CI runners
• Have a very large monorepo with many test suites
• Run tests in a tight loop (e.g., watch mode in CI)

Handling Rate Limits

When rate limited, the API returns:

• HTTP 429 status code
• Retry-After header with seconds until the limit resets

SDK Behavior

The Spekra SDK handles rate limits gracefully:

• Logs a warning message
• Does not fail your test run
• Does not retry automatically (to avoid CI delays)

# Example warning in CI logs
[spekra] Rate limit exceeded (429). Results for this run may be incomplete.

Strategies to Avoid Rate Limits

1. Reduce Parallelization

If running many test suites in parallel, consider:

# GitHub Actions example - limit concurrent jobs
jobs:
  test:
    strategy:
      max-parallel: 5  # Limit concurrent test jobs

2. Consolidate Test Runs

Instead of running multiple small test suites separately, consider running them as one suite:

# Instead of:
npx playwright test tests/auth/
npx playwright test tests/api/
npx playwright test tests/ui/

# Consider:
npx playwright test

3. Add Delays Between Runs

For repeated runs (e.g., matrix builds), add small delays:

# GitHub Actions example
- name: Wait before test run
  run: sleep ${{ matrix.index * 5 }}

Requesting Limit Increases

If you consistently need higher limits, contact us:

1. Email support@spekra.dev
2. Include your organization name
3. Describe your use case and volume needs

We're happy to work with teams that have legitimate high-volume needs.

Monitoring Your Usage

Usage statistics are available in Settings → API Keys. Each API key shows:

• Recent request counts
• Time until limit resets
• Any rate limit events

Rate Limit Response

When rate limited, the API returns:

{
  "error": "rate_limit_exceeded"
}

Response headers:

Next Steps

• API Keys - Managing your API keys
• Troubleshooting - Common issues and solutions
• CI/CD Integration - Optimizing your CI setup