InBetween

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:

KeyPrefixWhere to use itCan call
Secret keysk_Server-side onlyEvery endpoint
Public keypk_Browsers, mobile apps, the widgetAll read-only endpoints (below)

Public keys can call:

  • POST /v1/search
  • GET /v1/find
  • GET /v1/find/deduce
  • GET /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:

PlanRequests per second
Build2
Launch5
Grow15
Scale50
EnterpriseCustom

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:

429 Too Many Requests
{
  "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
  }
}
402 Payment Required
{
  "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.

StatustypecodeMeaningWhat to do
401authentication_errorMISSING_API_KEYNo API-Key header was sent.Add the header.
401authentication_errorFAILED_AUTH_CHECKThe 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.
401authentication_errorINVALID_API_KEYThe key was found but isn't a public (pk_) or secret (sk_) key.Use a key from the dashboard access page.
401authentication_errorPUBLIC_KEY_RESTRICTEDA public key was used on an endpoint that needs a secret key.Call this endpoint from your server with sk_.
402billing_errorINSUFFICIENT_CREDITYour balance can't cover the request.Top up or upgrade on the billing page.
429rate_limit_errorSECOND_LIMIT_EXCEEDEDToo 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:

400 Bad Request
{
  "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"
}
StatusWhen
400The 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.
400A locationName couldn't be found (search and find). The message is could not find location '<name>'.
404No venue exists with the ID you sent (detail and menus endpoints).
500Something went wrong on our side or with an upstream provider. Safe to retry with backoff.

Handling errors

Example error handling
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.

HeaderExampleDescription
X-Cost-Pence0.8Cost of this request. A Ranked Search is 0.8p at list price.
X-Consumed-FromSubscriptionWhich balance paid: Subscription, Personal, PersonalAndSubscription or NoCharge.
X-Remaining-Subscription-Balance931.2Monthly included usage remaining.
X-Remaining-Personal-Balance500Top-up balance remaining.

These headers are exposed to JavaScript, so you can read them in a browser as well as on your server.

Next steps

On this page