How is throttling signalled? Distinguishing "no slots" from "rate limited"

API General
1

We run an automated booking assistant against your API (common server,
non-enterprise). Our normal load is well under 1,000 requests per day, within the
2 parallel / 5 per second limits in section 4.2 of your Terms.

On 31 August a scheduling bug on our side temporarily generated far more requests
than our normal load. It has been fixed. But it exposed a problem we cannot solve
from the documentation, and it is a correctness problem rather than a capacity one.

During that period we received responses that arrived as HTTP 200 with an empty
result set, rather than an error. Our software cannot distinguish those from a
genuine “no appointments available”. The consequence is that we would tell a
patient nothing is free when in fact something is.

We have checked the developer API page, the API explorer and the user API guide,
and we cannot find anything describing rate-limit or throttling behaviour. Hence
these questions:

  1. When a request is throttled, or a limit is reached, what does the API return
    exactly? An HTTP status, a JSON-RPC error code, an empty result, or a delayed
    response?

  2. Is there any field, header or error code that identifies a throttled response,
    so we can detect it in code and retry, instead of reporting a false “nothing
    available” to the patient?

  3. Can error -32600 ever indicate throttling? The documentation describes it as
    expired token / access denied, and we want to be sure we are not misreading it.

  4. Are the figures in section 4.2 — 2 parallel, 5 per second, 5,000 per day —
    enforced as hard limits, or as fair use? In other words, what happens at
    request 5,001?

  5. Our admin instance is at a .simplybook.it address while your help pages only
    document *.simplybook.me. Can you confirm .it is an official SimplyBook.me
    domain?

We are not asking for higher limits; our usage fits comfortably. We need to know
how to recognise a throttled response so we never give a patient wrong information.

3

Hello,

  1. What does the API return when throttled?
    The JSON-RPC API has only one enforced limit: a daily call counter per company. When that daily cap is exceeded, the response is:

    • HTTP 200 (no status code is ever set for this path)
    • A JSON-RPC error body: {"error": {"code": -32600, "message": "Too many requests"}}

    So a real hard rate-limit rejection is never silent — it comes back as a JSON-RPC fault, not an empty result set

  2. Is there a field/code that identifies throttling specifically?
    No dedicated code. -32600 is reused for several unrelated cases — access denied, expired token, generic invalid request, company-not-found, and “too many requests.” The only thing that distinguishes them is the message text: “Too many requests” specifically means the daily quota was hit. If you were seeing -32600 with a different message (“Access denied”, “Invalid request”, etc.) that’s not a throttle — it’s one of the other cases (e.g. expired token)

  3. Can -32600 mean throttling?
    Only when message is exactly “Too many requests”

  4. Are the 4.2 figures (2 parallel / 5 per second / 5,000 per day) hard limits or fair use?
    There is no enforcement anywhere for “2 parallel” or “5 per second”. The only thing actually enforced is the daily counter described above. So in practice: the parallel/per-second figures in 4.2 are a fair-use description with nothing technically enforcing them; only the daily cap can actually reject a request, and it does so with an explicit error, not silence.
    This means your empty-result-during-the-spike symptom does not match how throttling behaves in this API. Given your normal load (<1,000/day) plus a temporary spike, even if you had hit the daily limit, you’d have received the explicit -32600 / "Too many requests" error, not HTTP 200 with an empty array. That points to something else causing the empty results during that window — possibly unrelated to rate limiting entirely (e.g. a genuine availability/timeout condition on our side during the load spike). I’d want to see actual request/response logs from your side for 31 August to investigate further if necessary.

  5. Is .simplybook.it official?
    Yes — simplybook.it is a legitimate first-party production domain (EU cluster), used throughout our own backend for company-admin/API routing. It’s not a typo or unofficial mirror; the docs pages simply haven’t been updated to mention it alongside .me.