Errors

Every error from Moymo's API has the same shape, so one piece of code can handle them all.

Response403ForbiddenJSON

{
  "timestamp": "2026-11-03T14:05:00.123Z",
  "status": 403,
  "code": "ACCESS_DENIED",
  "message": "This token does not have the servers scope",
  "path": "/api/app/v1/users/@me/servers",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Field
status	The HTTP status, repeated.
code	A stable machine-readable code. Branch on this, not on the message.
message	A sentence for a person. It may be reworded at any time.
path	The path you called.
traceId	An id for this request. Quote it when you ask for help: it lets us find exactly what happened.
fieldErrors	For validation failures: {"name": ["must not be blank"]}. Left out otherwise.

Nothing in an error reveals stack traces, SQL, or whether a given account exists.

Codes

code	Status	Meaning
VALIDATION_FAILED	400	The request is malformed or a value is not allowed. message says which.
AUTHENTICATION_REQUIRED	401	No credential, or one Moymo does not recognise: a wrong bot token, an expired or revoked access token, a suspended application.
ACCESS_DENIED	403	The credential is valid but may not do this: a missing scope, or a missing permission in a server.
NOT_FOUND	404	There is no such thing, or you may not know whether there is.
CONFLICT	409	The request is fine but cannot be done in the current state: a username is taken, a limit is reached, the person adding a bot lacks Manage Server.
RATE_LIMITED	429	Too many requests. See Rate limits.
PAYLOAD_TOO_LARGE	413	A body or a file is too big.
SERVICE_UNAVAILABLE	503	Something Moymo depends on did not answer (for example DNS during a domain check). Try again.
INTERNAL_ERROR	500	Our mistake. Quote the traceId.

OAuth2 endpoints

The token and revoke endpoints answer in the standard OAuth shape instead ({"error": "invalid_grant", "error_description": "..."}), because every OAuth library expects that.

Handling errors well

• Retry only what can succeed: 429 (after the wait), 503 and network errors, with backoff. Never retry a 4xx that is not 429 unchanged.
• 401 on a bot token means the token was reset or the application was suspended or deleted. Stop and alert a person; do not hammer the API.
• 401 on an access token means it expired (try the refresh token once) or the member revoked access (treat the member as signed out).
• 403 with a bot usually means a permission the server did not give. Say so in your bot's own words instead of failing silently.