Authentication & Errors
API keys, which endpoints each key can call, rate limits, error responses and billing headers.
API keys
Every request must include your key in the API-Key header:
curl "https://api.inbe.us/v1/find?name=padella" \
-H "API-Key: $INBE_API_KEY"Not a bearer token
The key goes in API-Key, not Authorization: Bearer …. Requests with only
an Authorization header are rejected with MISSING_API_KEY.
Your keys are on the access page in the dashboard. The prefix tells the API which type of key it is:
| Key | Prefix | Where to use it | Can call |
|---|---|---|---|
| Secret key | sk_ | Server-side only | Every endpoint |
| Public key | pk_ | Browsers, mobile apps, the widget | All read-only endpoints (below) |
Public keys can call:
POST /v1/searchGET /v1/findGET /v1/find/deduceGET /v1/establishments/basic/{id}GET /v1/establishments/advanced/{id}GET /v1/establishments/menus/{id}GET /v1/widget/simple-widget.js
Today every public endpoint is read-only, so both key types can call all of them. Requests made with either key are billed to your account, so treat a public key as something that can be extracted and used by others. See Setup for how to choose between them.
Calling from a browser
The API supports CORS, so you can call it from a web page with a public key. Browsers may send the API-Key and Content-Type request headers, and JavaScript can read the billing headers and Retry-After on responses.
Rate limits
Rate limits are applied per account (not per key), based on your plan:
| Plan | Requests per second |
|---|---|
| Build | 2 |
| Launch | 5 |
| Grow | 15 |
| Scale | 50 |
| Enterprise | Custom |
Limits are per second only. There are no daily request quotas: your spend is limited by your credit balance instead. See Billing.
When you go over your limit the API responds with 429 Too Many Requests, the error code SECOND_LIMIT_EXCEEDED and a Retry-After: 1 header. Wait that many seconds and retry. Rate-limited requests are not charged and don't count towards your limit.
Error responses
Errors come in two shapes.
Key, credit and rate-limit errors (401, 402, 429)
Problems with your key, credit or rate limit return a structured body:
{
"error": {
"message": "Rate limit exceeded. Too many requests per second.",
"type": "rate_limit_error",
"code": "SECOND_LIMIT_EXCEEDED",
"limit": 5,
"reset": "1s",
"currentCount": 6,
"retryAfterSeconds": 1
}
}{
"error": {
"message": "You ran out of credit. Please top up!",
"type": "billing_error",
"code": "INSUFFICIENT_CREDIT"
}
}limit, reset, currentCount and retryAfterSeconds are only present on rate-limit errors.
| Status | type | code | Meaning | What to do |
|---|---|---|---|---|
| 401 | authentication_error | MISSING_API_KEY | No API-Key header was sent. | Add the header. |
| 401 | authentication_error | FAILED_AUTH_CHECK | The key isn't recognised, or it has been revoked or has expired. | Check for copy/paste errors, then compare with the key on the dashboard access page. |
| 401 | authentication_error | INVALID_API_KEY | The key was found but isn't a public (pk_) or secret (sk_) key. | Use a key from the dashboard access page. |
| 401 | authentication_error | PUBLIC_KEY_RESTRICTED | A public key was used on an endpoint that needs a secret key. | Call this endpoint from your server with sk_. |
| 402 | billing_error | INSUFFICIENT_CREDIT | Your balance can't cover the request. | Top up or upgrade on the billing page. |
| 429 | rate_limit_error | SECOND_LIMIT_EXCEEDED | Too many requests per second. | Wait for Retry-After seconds, then retry. |
Request and server errors
Other errors return a flat body with a single error string:
{
"error": "you submitted an incorrectly formatted id. please make sure that the input id is a valid UUID. docs: https://www.inbe.us/docs/api/detail/basic"
}| Status | When |
|---|---|
| 400 | The body isn't valid JSON, a field has the wrong type, a query parameter can't be parsed, or a venue ID isn't a UUID. |
| 400 | A locationName couldn't be found (search and find). The message is could not find location '<name>'. |
| 404 | No venue exists with the ID you sent (detail and menus endpoints). |
| 500 | Something went wrong on our side or with an upstream provider. Safe to retry with backoff. |
Handling errors
async function inbe(path: string, init: RequestInit = {}) {
const res = await fetch(`https://api.inbe.us${path}`, {
...init,
headers: {
"Content-Type": "application/json",
"API-Key": process.env.INBE_API_KEY!,
...init.headers,
},
});
if (res.ok) return res.json();
const body = await res.json().catch(() => ({}));
if (res.status === 429) {
// Wait for Retry-After (always 1 second today), then retry.
const seconds = Number(res.headers.get("Retry-After") ?? 1);
await new Promise((r) => setTimeout(r, seconds * 1000));
return inbe(path, init);
}
const message =
typeof body.error === "string" ? body.error : body.error?.message;
throw new Error(`InBe ${res.status}: ${message ?? res.statusText}`);
}Add a retry limit before you use this in production.
Billing headers
Successful billable responses include headers showing what the request cost and what you have left. All amounts are in pence.
| Header | Example | Description |
|---|---|---|
| X-Cost-Pence | 0.8 | Cost of this request. A Ranked Search is 0.8p at list price. |
| X-Consumed-From | Subscription | Which balance paid: Subscription, Personal, PersonalAndSubscription or NoCharge. |
| X-Remaining-Subscription-Balance | 931.2 | Monthly included usage remaining. |
| X-Remaining-Personal-Balance | 500 | Top-up balance remaining. |
These headers are exposed to JavaScript, so you can read them in a browser as well as on your server.