Docs Errors and limits

Errors and limits

The shape of an error, what each type means, and the rate limits.

Documentation

Every error is an RFC 9457 problem:

{ "type": "/errors/not-found", "title": "Not Found", "status": 404,
  "detail": "Conversation not found: 261009174512A1B2C3D4E5F6", "trace_id": "9f2c41d07a6b3e58" }

Match on type, show detail, quote trace_id when asking why: it finds the request in the server's log, and is the caller's own X-Request-Id when one was sent.

type Status
bad-request 400 the request makes no sense as it is; detail says what
validation 400 with errors: [{ "field": "members[0].id", "message": "must not be blank" }]
unauthorized 401 no credentials, or not accepted
quota-exceeded 402 the app holds as much as its plan allows of what quota names (users, conversations, messages or files); limit says how much that is, and plan which plan it is on
forbidden 403 signed in, and not allowed this
not-found 404 not there, or not for the caller to know of: the two are answered alike
conflict 409 does not fit what is on record, e.g. leaving a direct conversation
unprocessable 422 well formed and cannot be carried out, e.g. names a user who does not exist
too-large 413 an upload over the limit, or a body larger than the server reads (4 MB of JSON)
rate-limited 429 with Retry-After and retry_after_ms
internal-error 500 the server's fault; nothing of its inside is in the answer
unavailable 503 something the server needs, such as the store its files are in, cannot be reached just now: try again after Retry-After
insufficient-storage 507 no room for files on the server just now: try the upload again later

Rate limits apply to users with a token of their own, per user: 30 messages at once and 120 a minute (sending, editing, reacting), 10 uploads at once and 30 a minute and 1 GB of them in 24 hours, 20 other changes at once and 60 a minute. What takes the database a search has a limit too, 30 at once and 120 a minute: searching a conversation, and asking after the presence of many users (GET /presence, presence.subscribe); of searches, four are under way on a server at a time, and one more is answered 429 to come back in a second. And so has what is only told to the others in a conversation, typing and what was read or received: 300 at once, since a client that connects again says what it has received everywhere, and 600 a minute. Your server, with its API key, acting as a user or not, has limits of its own, for the whole app and far above a person's: 600 messages at once and 6,000 a minute, 120 uploads at once and 1,200 a minute, 600 other changes at once and 6,000 a minute (the tokens it asks for included, the endpoints of webhooks it registers or changes, and every user it names for the first time, in X-Bonga-User too), 600 searches at once and 6,000 a minute, 3,000 of what is only told at once and 12,000 a minute, and five test deliveries of a webhook at once and ten a minute. They are there so that no app can take the server for itself, however it came by its key; an app that reaches them needs them raised.

Plans say how much an app may hold. Every app starts on the Free plan; Plus, the paid plan, holds more.

An app may hold Free Plus
users 1,000 100,000
conversations, direct ones and groups 10,000 1,000,000
messages 100,000 10,000,000
files 5 GB 50 GB

An app that holds as much of a kind as its plan allows is refused more of that kind, and nothing else: the request that would make a user, a conversation, a message or a file is answered 402 with the type quota-exceeded, on a connection as an error frame with that status, and quota, limit and plan say which limit it was. All the app holds stays, and is read, changed and deleted as before; its users sign in, and a group is joined and left. It has room again when it holds less, or on the other plan.

  • A user counts from the first time the app names them: with a token, with PUT /users/{userId}, in X-Bonga-User, as a member of a conversation, or by signing in with a token of their identity provider. A user who is deactivated still counts.
  • A message counts for as long as its conversation is there: a deleted message keeps its place in the conversation, and the notes the server writes into a conversation (somebody joined, the title changed) are messages. An app that holds as many messages as it may gets no more such notes: what a note would have said is done all the same, and told to the clients as it happens.
  • Files are counted by what they take in storage, the previews of images included, at every upload. The upload that goes past the limit is still taken; the next is refused.
  • Users, conversations and messages are counted about once a minute: an app that deleted something has room again within a minute.

An app is moved to Plus by whoever runs the server, once it has been paid for.

An app that needs more room is made Plus by hand, for USD 49 a month for each app; one that needs higher rate limits can ask for them. Write to support@foxshard.com. Name the app by its key, and never send an API key.