Responses & errors

Every /user, /bots and /groups response uses the same envelope. Check success first; the result is in data, the problem in error.

Success

HTTP 200

{
  "success": true,
  "data": { "result": "OK", "action": "group_invite" },
  "meta": { "timestamp": "2026-10-02T12:00:00.000Z", "version": "1.0" }
}

The API refused the request

success is false and the HTTP status is 4xx or 5xx.

HTTP 403

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token does not have required scope: bots:groups",
    "details": {
      "required_scope": "bots:groups",
      "accepted_scopes": ["bots:groups"],
      "provided_scopes": ["read:profile", "bots:chat"]
    }
  },
  "meta": { "timestamp": "2026-10-02T12:00:00.000Z", "version": "1.0" }
}

The bot couldn't do it

The request was fine and reached the bot, but the bot couldn't carry it out — an invite still on cooldown, an avatar that doesn't exist. The HTTP status is still 200 and success is true; the outcome is in data.result ("OK" or "FAIL") with the reason in data.resulttext.

HTTP 200

{
  "success": true,
  "data": {
    "success": false,
    "result": "FAIL",
    "resulttext": "Invite on cooldown. 240s remaining.",
    "action": "group_invite"
  },
  "meta": { "timestamp": "2026-10-02T12:00:00.000Z", "version": "1.0" }
}

Some Second Life actions never report failure. An invite or eject in a group where the bot lacks that power returns "OK" but does nothing.

Error codes

Code	HTTP	Meaning
`INVALID_TOKEN`	401	The token is missing, revoked or expired. Refresh it, or send the user through authorization again.
`INSUFFICIENT_SCOPE`	403	The token lacks the scope this endpoint needs. details lists the accepted and provided scopes.
`MISSING_PARAMETERS`	400	A required parameter is missing.
`INVALID_PARAMETER`	400	A parameter has the wrong format or value, e.g. a UUID that isn't one.
`BOT_EXPIRED`	409	The bot's subscription has expired, so it cannot be started.
`PASSWORD_REQUIRED`	409	The bot has no Second Life password stored. The owner must set it on lifebots.cloud.
`NO_HOSTING_CHANNEL`	409	The bot has no hosting slot assigned. Contact LifeBots support.
`BOT_NOT_FOUND`	404	No bot with that id belongs to the user.
`GROUP_NOT_FOUND`	404	The group isn't registered to the user (Registered Groups endpoints only).
`GROUP_NOT_ACTIVE`	400	The registered group isn't running — for example it is unpaid, expired, or its bot is not in the group.
`USER_NOT_FOUND`	404	The user's profile or avatar link is missing.
`CANNOT_REVOKE_CURRENT_TOKEN`	400	An app tried to revoke its own access with the token making the call.
`COMMAND_FAILED`	500	The bot could not be reached or the command threw. details.error says why, e.g. "Bot is not online."
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Wait for Retry-After seconds.
`INTERNAL_ERROR`	500	Something failed on our side. Safe to retry later.

OAuth endpoint errors

/oauth/token, /oauth/tokeninfo, /oauth/userinfo and /oauth/revoke follow the OAuth 2.0 standard instead: no envelope, and errors carry error and error_description.

HTTP 400

{
  "error": "invalid_grant",
  "error_description": "Invalid or expired authorization code"
}

error	Meaning
`invalid_request`	A required parameter is missing, or PKCE is missing for a public app.
`invalid_client`	Unknown `client_id` or wrong `client_secret`.
`invalid_grant`	The code or refresh token is wrong, expired or already used, the `redirect_uri` doesn't match, or the `code_verifier` is wrong.
`unauthorized_client`	Token refresh is turned off for this app.
`unsupported_grant_type`	Use `authorization_code` or `refresh_token`.
`invalid_token`	The bearer token is missing, revoked or expired.
`insufficient_scope`	The token lacks `read:profile` (userinfo).

Rate limits

Endpoints	Limit	Counted per
`/oauth/*`	10 requests / minute	IP address
`/bots/*`	60 requests / minute	Access token
`/user/, /groups/`	100 requests / minute	Access token

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get 429RATE_LIMIT_EXCEEDED and a Retry-After header — wait that many seconds before trying again.