Modbot Docs
API

Errors

What a Modbot API error looks like, and every code it can carry.

Every error from the Modbot API has the same shape, whatever went wrong and whichever endpoint you called. It is application/problem+json, the standard shape for HTTP API errors, with one field added: code.

{
  "type": "https://docs.modbot.co/api/errors/#needs-permission",
  "title": "Needs a permission",
  "status": 403,
  "detail": "This needs the ViewAuditLog permission.",
  "code": "needs-permission",
  "error": "This needs the ViewAuditLog permission.",
  "neededPermissions": ["ViewAuditLog"]
}
Field
codeWhat went wrong, as a word your program can compare. See the codes.
detailThe same, as a sentence for a person. It can change between releases; do not compare it.
statusThe HTTP status, repeated.
titleThe code in a few words.
typeA link to the code's entry on this page.
errorThe same sentence as detail. Kept for one more API version for programs written before detail existed; read detail instead.

Some errors carry more fields beside these, named in the endpoint's entry in the API reference. The common ones:

FieldOn
neededPermissionsneeds-permissionThe names of the permissions the endpoint needs, as on Roles.
missingGroupPermissionvrchat-refusedThe group permission Modbot's own VRChat account is missing, when that is why VRChat said no.
caseIdconflict on a case fileThe case file that already exists.

An error under /api with no body at all came from something in front of Modbot, such as a proxy, or is a 500 from a crash inside Modbot, whose log says what happened.

Reading an error

Branch on code. New codes can be added in any release, so treat a code you do not know by its HTTP status: a 4xx you cannot fix by asking again, a 5xx you might.

const answer = await fetch('https://modbot.example.com/api/group/invites', {
  method: 'POST',
  headers: { Authorization: 'Bearer mbk_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: 'usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469' }),
})

if (!answer.ok) {
  const problem = await answer.json()
  if (problem.code === 'too-many-requests') {
    // Wait as long as Retry-After says, then ask again.
  } else {
    console.error(problem.detail)
  }
}

A code is never renamed and never reused to mean something else.

The codes

invalid-request

400. Something in the request is missing or has a value Modbot cannot use. detail says what.

not-signed-in

401. No key, a key that is wrong, expired or revoked, a key sent where keys are not allowed, or an account that is disabled. Modbot never says which, so it never says whether a key exists.

needs-permission

403. Signed in, but without a permission this needs. neededPermissions names them.

vrchat-not-linked

403. The account has not linked its VRChat account yet, and nothing but the link works until it has.

refused

403. Modbot will not do this here, whoever asks: signing in on a demo, or acting on the bot's own Discord account, the server's owner or a Discord account linked to a staff account, for example.

not-found

404. That thing does not exist, or no longer does: a role somebody deleted in VRChat, say.

wrong-method

405. The address exists, but not with that method: a GET to an address that only takes POST.

conflict

409. It clashes with something as it stands: a name already taken, a flag already closed.

no-group

409. No VRChat group has been chosen yet, so there is nothing to act in.

gone

410. It existed and was removed for good, like evidence that was destroyed.

too-large

413. The upload or body is larger than Modbot accepts.

wrong-content-type

415. The body is not in a format the endpoint reads.

not-possible

422. Modbot understood the request and cannot do it as things stand. detail says why.

too-many-requests

429. One of Modbot's own limits: one group invite every thirty seconds, for example. A Retry-After header says how many seconds to wait when Modbot knows.

vrchat-rate-limited

429. VRChat asked Modbot to slow down, or Modbot is pausing its own calls to VRChat to stay under VRChat's limits. Modbot never asks VRChat again by itself; ask again later.

server-error

500. Something went wrong inside Modbot. Its log says what.

not-available

501. This Modbot cannot do this at all.

vrchat-refused

502. VRChat turned the request down. detail is what VRChat said, and missingGroupPermission names the group permission Modbot's VRChat account lacks when that was the reason.

discord-refused

502. Discord turned the request down, often because the bot lacks a Discord permission or its role is below the person's. detail is what Discord said.

service-failed

502. Another service Modbot asked failed: the AI provider, or Modbot Cloud.

not-set-up

503 (or 409). Something this needs has not been set up on this Modbot: a VRChat account, a Discord server, evidence storage.

unavailable

503. Something this needs is not reachable right now, such as the Discord bot. Asking again later can work.

timed-out

504. Something Modbot asked took too long to answer.

What does not use this shape

  • An answer that VRChat itself gave, passed on by the VRChat proxy, is VRChat's own, untouched. The proxy's own refusals (switched off, no permission) use this shape.
  • The companion's connection (/api/v1/companion/...) has error codes of its own.
  • Sign-in for AI apps over MCP (/mcp/...) follows the OAuth standard's own error shape.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page