Get started

Errors and limits

Every failure has the same shape and a stable code. The hint says what to do next, written for a person or the AI app working for them.

The error body

429 Too Many Requests

{
  "code": "RATE_LIMITED",
  "message": "Too many requests. Wait and retry.",
  "requestId": "4f0c9a2e-61b7-4d1a-9b55-2d6c1f1e7a10",
  "retryAfterSeconds": 12,
  "hint": "Wait 12 seconds, then send the same request again."
}

code and reason are stable: branch on them, never on the message. Quote requestId when you contact support. Errors that can succeed later also send a Retry-After header.

Codes

CodeStatusRetryMeaning

VALIDATION_FAILED400noThe request is not valid.

UNAUTHENTICATED401noSign in to continue.

PAYMENT_REQUIRED402noThis feature needs a paid plan.

FORBIDDEN403noYou are not allowed to do this.

FEATURE_NOT_ENABLED403noThis feature is not enabled. Enable it in the HeyBMO marketplace.

NOT_FOUND404noNothing was found.

CONFLICT409noThis conflicts with existing data.

QUOTA_EXCEEDED413noA limit was reached. Remove something no longer needed, then try again.

CONFIRMATION_REQUIRED428noNothing was changed: this needs to be confirmed first.

RATE_LIMITED429yesToo many requests. Wait and retry.

INTERNAL500yesSomething went wrong on our side.

UNAVAILABLE503yesHeyBMO is briefly unavailable.

Rate limits

Each operation has a policy, counted per person and per address over a sliding window. The policy of every operation is shown in the API reference.

PolicyPer personPer addressUsed for

read600 / minute1,200 / minuteReading data

write120 / minute300 / minuteCreating and changing data

delete30 / minute60 / minuteDeleting data, slower on purpose

upload120 / hour240 / hourAsking for upload links

expensive10 / minute20 / minuteCostly work such as exports

Deleting for good

Operations that delete permanently never act on the first call. They answer CONFIRMATION_REQUIRED with what would be deleted; show that to the person, then send the same call with "confirm": true in the input. A few changes, such as switching a feature off, can only be approved by the person in HeyBMO itself.