FAQ & Troubleshooting

Frequently Asked Questions

How do I get an API key?

Go to BounceWatch Dashboard
Sign in or create an account
Your API key will be displayed on the dashboard
Copy it and add to your requests as X-API-Key header

How does the enrichment process work?

The API now operates in a single unified mode — no need to choose between cached and realtime.How it works:

Send a request to GET /api/v1/company/stripe.com
If data was enriched within the last 24 hours → instant response (< 250ms, no charge)
If no recent data → enrichment triggers automatically (202 Accepted)
Results are delivered to your webhook (2-10 minutes)
Subsequent requests within 24h get the data instantly for free

Webhook is required for new enrichments. Configure it in your API Panel or use the X-Webhook-URL header.

For quick testing, get a free webhook URL from webhook.site

# Simple request - API handles everything
GET /api/v1/company/stripe.com?enrich=funding,team

How are credits calculated?

Each request costs credits based on modules requested:

Module	Credits
Base (always included)	10
Business	+6
Technology	+4
Funding	+10
Team	+6
Signals	+16
Competitors	+8

Example: Base + Funding + Team = 10 + 10 + 6 = 26 credits

If you query the same domain within 24 hours, you won’t be charged again.

What happens if a company is not in your database?

When you request a domain that’s not in our database:

We automatically trigger a realtime enrichment
You receive a 202 Accepted response with a batch_id
Fresh data is collected and sent to your webhook
You can also poll the status endpoint

This ensures you always get data, even for new companies.

Do credits expire?

Yes — credits do not roll over. Each billing period starts at your plan’s allowance, whatever was left of the previous one.On a 25,000-credit plan with 8,000 unspent at renewal, the new period begins at 25,000 — not 33,000. The allowance is what the period buys, not a balance that accumulates.

The one exception is a mid-cycle upgrade: you are charged for the new plan immediately, so the credits you had already paid for are carried over and the new plan’s allowance is added on top.

Check your credit balance anytime:

GET /api/v1/account/credits

Can I test the API before purchasing?

Yes! New accounts receive 2,500 free trial credits to test the API.Trial credits are one-time — they are not renewed. Trial rate limits:

60 requests/minute
500 requests/day

What data sources do you use?

BounceWatch aggregates data from multiple public sources:

Company websites and blogs
LinkedIn company pages
News articles and press releases
Public funding databases
Job boards and career pages
Technology detection platforms
Government registries and public filings
Social media and professional networks

Data freshness varies by source and company activity level.

How often is the data updated?

Data freshness depends on the company and data type:

Data Type	Typical Freshness
Base info	1-4 weeks
Funding	Real-time (when announced)
Team/Jobs	1-2 weeks
Technology	2-4 weeks
Signals	Real-time

Use the enrich parameter when you need specific data modules for a domain.

Troubleshooting

Authentication Errors

401 Unauthorized - Invalid API key

Problem: Your API key is not recognized.Solutions:

Check for typos or extra spaces in your API key
Ensure you’re using the header X-API-Key (case-sensitive)
Verify your key hasn’t been regenerated in the dashboard

Keys start with bw_. There is no separate test key — every key is live.

# Correct
curl -H "X-API-Key: bw_abc123..." https://api.bouncewatch.com/api/v1/company/stripe.com

# Wrong header name
curl -H "Authorization: Bearer bw_abc123..." # ❌ Won't work
curl -H "Api-Key: bw_abc123..." # ❌ Won't work

401 Unauthorized - API key missing

Problem: No API key provided in the request.Solution: Add the X-API-Key header to your request:

curl -X GET "https://api.bouncewatch.com/api/v1/company/stripe.com" \
  -H "X-API-Key: YOUR_API_KEY"

Credit Errors

402 Payment Required - Insufficient credits

Problem: Not enough credits for the requested modules.Response:

{
  "success": false,
  "error": "insufficient_credits",
  "message": "Request requires 26 credits, you have 15 remaining",
  "credits_required": 26,
  "credits_available": 15
}

Solutions:

Request fewer enrichment modules
Upgrade your plan — an upgrade mid-period keeps your remaining balance and adds the new plan’s allowance on top
Wait for the next billing period (the balance resets to your plan’s allowance; it does not roll over)
Check if you recently queried this domain (no charge for 24h)

One-time credit packs are not available yet. If an upgrade is the wrong shape for a one-off spike, email us and we will sort it out manually.

Rate Limit Errors

429 Too Many Requests - Rate limit exceeded

Problem: You’ve exceeded your rate limit.Response:

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "retry_after": 45
}

Solutions:

Wait for the retry_after period
Implement exponential backoff in your code
Spread requests evenly over time
Upgrade to a higher plan for increased limits

Rate limits by plan:

Plan	Requests/Minute
Free Trial	10
Starter	30
Professional	60
Business	90
Enterprise	120

Domain Errors

400 Bad Request - Invalid domain format

Problem: The domain format is not valid.Solutions:

Use clean domains without protocols: stripe.com ✅
Don’t include https:// or www.: https://www.stripe.com ❌
Don’t include paths: stripe.com/about ❌

# Correct
GET /api/v1/company/stripe.com

# These also work (we clean them automatically)
GET /api/v1/company/https://stripe.com
GET /api/v1/company/www.stripe.com

We have no data for this domain

This is not a 404. For a domain we have never seen, the API queues an enrichment and answers 202 Accepted with a batch_id. Results reach your webhook when ready.If nothing is found, the batch finishes as no_data_found, your credits are refunded in full, and the domain goes on a 24-hour cooldown — asking again inside that window returns 409 no_data_cooldown with a Retry-After header.If a domain repeatedly returns no data:

It might not be a company website
The company might be too small or too new to have a public footprint
Check the spelling

409 Conflict - already enriching, or recently enriched

Not a failure. We deduplicate per domain so you are never charged twice for the same work. Check the error field:

`error`	Meaning	What to do
`enrichment_in_progress`	A scan for this domain is already running	Wait for the webhook
`recently_enriched`	Enriched within the last 24 hours	Call `GET /company/{domain}` again — you get the data free
`no_data_cooldown`	We recently found nothing here	Honour the `Retry-After` header

Treating 409 as a hard error is the most common integration mistake — it usually means the data you want is either on its way or already free to fetch.

Webhook Errors

Webhooks not being received

Problem: Your endpoint isn’t receiving webhook notifications.Checklist:

HTTPS required: Your webhook URL must use HTTPS
Publicly accessible: Your endpoint must be reachable from the internet
Responds quickly: Return 200 OK within 30 seconds
Check firewall: Allow traffic from BounceWatch IPs
Verify URL: Ensure the URL is correctly configured

Test your endpoint:

# Use webhook.site for testing
curl -X POST "https://api.bouncewatch.com/api/v1/account/webhook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://webhook.site/YOUR-ID", "events": ["enrichment.completed"]}'

Webhook signature verification failing

Problem: Your signature validation is rejecting webhooks.Common causes:

Wrong secret: Using old webhook secret after regeneration
Payload modified: Parsing/reformatting the raw payload before verification
Clock skew: Server time significantly different from UTC

Debug steps:

// Log raw values before verification
console.log('Timestamp:', timestamp);
console.log('Signature:', signature);
console.log('Payload (raw):', payload);
console.log('Secret (first 10 chars):', secret.substring(0, 10));

Realtime Enrichment Errors

Enrichment stuck in 'processing' status

Problem: Realtime enrichment hasn’t completed.Expected times:

Most enrichments complete in 3-8 minutes
Complex requests with all modules may take up to 12 minutes

If stuck for over 30 minutes:

Check the status endpoint for error messages
The domain might have limited public data
Contact support if the issue persists

GET /api/v1/enrichment/{batch_id}/status

Enrichment completed but data is sparse

Problem: Realtime enrichment completed but some fields are null.Reasons:

Company has limited online presence
Specific data type not publicly available
Company is new or very small

Tips:

Not all fields are available for all companies
Larger, more active companies have more data
Some data (funding, team) requires public disclosure

Need More Help?

Contact Support

Email us for technical support or questions about the API

Getting Started

Core Concepts

AI Agents (MCP)

API Reference

API Playground

Frequently Asked Questions

Troubleshooting

Authentication Errors

Credit Errors

Rate Limit Errors

Domain Errors

Webhook Errors

Realtime Enrichment Errors

Need More Help?

Contact Support

​Frequently Asked Questions

​Troubleshooting

​Authentication Errors

​Credit Errors

​Rate Limit Errors

​Domain Errors

​Webhook Errors

​Realtime Enrichment Errors

​Need More Help?

Contact Support

Frequently Asked Questions

Troubleshooting

Authentication Errors

Credit Errors

Rate Limit Errors

Domain Errors

Webhook Errors

Realtime Enrichment Errors

Need More Help?