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}, inX-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.