Error Codes
All errors return JSON with error and code fields, even when the request specified an image format.
Error response format
{
"error": "No credits remaining",
"code": "PAYMENT_REQUIRED",
"buy_url": "/pricing"
}Error reference
| HTTP | Code | Error | Fix |
|---|---|---|---|
| 400 | BAD_REQUEST | Missing or invalid parameters | Check request body. brand is required. format must be json, png, or jpeg. |
| 401 | UNAUTHORIZED | Invalid or missing API key | Add the x-api-key header with a valid bm_live_* key. |
| 402 | PAYMENT_REQUIRED | No credits remaining | Purchase credits at /pricing (opens in a new tab) or switch to metered billing. |
| 404 | NOT_FOUND | No locations found for brand | Check brand spelling. Must match an indexed OSM brand tag exactly. |
| 429 | RATE_LIMITED | Too many requests | Reduce request frequency. See Rate Limits for tier details. |
| 500 | INTERNAL_ERROR | Server error or renderer failure | Retry after a few seconds. If persistent, contact support. |
Handling errors in code
const res = await fetch("https://api.brandmappr.com/api/v1/location-map", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.BRANDMAP_API_KEY
},
body: JSON.stringify({ brand: "Starbucks" })
});
if (!res.ok) {
const err = await res.json();
console.error(`${err.code}: ${err.error}`);
if (res.status === 402) {
// Redirect to purchase page
window.location.href = err.buy_url;
}
return;
}
const data = await res.json();