Why is my BNBCalc API request failing? (401, 403, 429 and timeouts)

Last reviewed Oct 21, 2026 by Jeremy Werden

Short answer

Most BNBCalc API failures come from a missing or wrong key (401), a key suspended after the API subscription ends or a second failed payment (403), a body that fails validation (400), too many requests (429), or a client timeout on an AI request. BNBCalc doesn't bill error responses, but it can bill a request your client abandoned.

What do the BNBCalc API's error codes mean?

When a request fails, the API answers with an HTTP status code and a JSON body like {"statusCode": 401, "success": false, "message": "Invalid API key"}. For validation errors, message is a list with one entry per problem. Either way, the message usually tells you exactly what's wrong:

Status	Message you'll see	What it means and what to do
400	A list of field problems, such as "accomodates must be a positive number"	The body failed validation. Check the field names (including `accomodates` with one "m"), types and ranges.
400	"Either (lat and lng) or fullAddress must be provided"	Send an address or a pair of coordinates
400	"Failed to geocode address: …" or "Failed to reverse geocode coordinates: …"	BNBCalc couldn't place the address or coordinates on the map. Send the full street address with city, state and ZIP code, or send coordinates.
400	"Set addAIComps and/or addAIExpenseEstimates to enhance an analysis"	An enhance call needs at least one of the two flags
401	"Missing API key. Provide x-bnbcalc-api-key header"	The header is missing or misspelled
401	"Invalid API key"	The key is wrong, or it was replaced when someone clicked Regenerate key
403	"API key is suspended or inactive"	Your API subscription has ended, or a payment on it has failed twice
403	"You are not authorized to enhance this analysis"	The enhance endpoint only works on analyses your own account created
404	"Analysis not found"	The `analysisId` sent to the enhance endpoint doesn't exist
429	"ThrottlerException: Too Many Requests", "AI request rate limit exceeded" or "Too many AI requests in flight (max 2 concurrent)"	You've hit a rate limit. Wait for the number of seconds in the `Retry-After` header, then try again.

Errors on the server's side come back as a 500 with "Internal server error". Like every other error response, they aren't billed, so a retry won't cost you twice.

Why is my API key being rejected?

Start with the header itself. The key goes in x-bnbcalc-api-key, exactly as spelled there, on every request, and a 401 with "Missing API key" means the server didn't find it. If the message is "Invalid API key" instead, the key you're sending isn't the current one. That happens when someone clicks Regenerate key, which retires the old key straight away, so copy the current key from Settings, then API.

A 403 with "API key is suspended or inactive" is about the subscription rather than the key. BNBCalc suspends the key when your API subscription ends, and also after a second failed payment on it. Once a payment goes through, the key works again, so update your card if a payment failed. If you canceled, or the payment retries ran out and the API subscription ended, start the API subscription again from the same page.

To test a key without creating an analysis, send a GET request to /v1/external/health with the header. A working key gets {"status": "ok"} back, and health checks aren't billed.

What are the BNBCalc API's rate limits?

The API allows up to 100 requests a second from one IP address. The enhance endpoint is tighter, at 5 a minute, and requests that ask for AI comps or AI expense estimates are limited to about 10 a minute per key, with no more than 2 running at once. Any request that sets addAIComps or addAIExpenseEstimates to true counts toward the AI limits, enhance calls included.

Going over a limit returns a 429 with a Retry-After header saying how many seconds to wait. Every response also carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and on requests with AI steps they track the AI limit, so your code can slow down before it hits the ceiling. If you're creating analyses in bulk, the simplest fix is to queue AI requests two at a time and no more than 10 a minute.

Why did my request time out?

Requests without AI steps usually come back within seconds, while AI comps and AI expense estimates have a 90-second budget. Even so, the API docs recommend a client timeout of at least 300 seconds for any request with AI steps.

Unfortunately, a timeout on your side doesn't stop the work on BNBCalc's side. If your client gives up first, the analysis may still be created and billed. Since the API has no endpoint to fetch an analysis again later, a retry creates, and bills, a second report. So make sure your timeout is long enough before you send AI requests in volume.

What do the warnings in a successful response mean?

Sometimes a request succeeds but an AI step doesn't finish, and what comes back depends on the endpoint. On a create request you still get the analysis, plus a warnings array explaining what was skipped, and the skipped step isn't billed. On an enhance call where nothing completes, you get only the warnings, and the call is free. These are the warnings you're most likely to see:

Warning	What happened	What to do
`ai_comps_photos_not_ready`	BNBCalc couldn't get enough usable listing photos in time: none were found, too few were usable, or they were still being gathered	Wait a few minutes and try the enhance endpoint once. If the warning comes back, use the analysis as it is.
`ai_comps_unavailable_for_property`	AI comps can't run for this property, for example because it's outside the US	Use the analysis as it is
`ai_comps_timed_out`	The AI step ran out of time	Try again later with the enhance endpoint
`ai_comps_run_in_progress`	An AI comps run is already going for this analysis	Wait for it to finish
`ai_comps_already_applied` or `ai_expense_estimates_already_applied`	That AI step had already been applied to the analysis	Nothing, since the analysis already has it
`ai_expense_estimates_failed`, `ai_expense_estimates_timed_out` or `ai_expense_estimates_no_proposals`	AI expense estimates didn't apply, so the analysis kept BNBCalc's standard expenses	Use the analysis as it is, or try the enhance endpoint later

How do I check my failed requests?

Open Settings, then API, in BNBCalc. The Status Codes breakdown on the API Usage card shows the requests that reached BNBCalc, including validation errors (400), missing analyses (404) and server errors (500). Requests turned away first, such as a missing or invalid key (401), a suspended key (403) or a rate limit (429), aren't recorded there, so make sure to log status codes in your own client to catch those.

Frequently asked questions

What does "Invalid API key" mean on the BNBCalc API?

The BNBCalc API returns a 401 "Invalid API key" when the key in your x-bnbcalc-api-key header isn't your account's current key, usually because someone clicked Regenerate key. Copy the current key from Settings, then API, in BNBCalc.

Why does the BNBCalc API say my key is suspended or inactive?

BNBCalc suspends an API key when your API subscription ends, or after a second failed payment on it. A successful payment reactivates the key, and after a cancellation you can start the API subscription again from Settings, then API.

Was this helpful?