# Errors

How Buun Identity says no. The OAuth endpoints answer in the protocol's own shape; everything else in one envelope of its own.

## OAuth endpoints

`/oauth/token` and `/oauth/revoke` answer `400` or `401` with `{ "error": "...", "error_description": "..." }`.

| `error` | Means |
|---|---|
| `invalid_request` | A field is missing or malformed |
| `invalid_client` | The client is unknown, disabled, or did not prove itself |
| `invalid_grant` | The code, refresh token or subject token is wrong, spent, expired, or not this client's. One message for every cause |
| `unauthorized_client` | This client may not use this grant |
| `unsupported_grant_type` | The grant type is not one Buun Identity supports |
| `invalid_scope` | A scope is unknown or not allowed for this client |
| `invalid_target` | The `resource` is not one this client may ask for, or not one a token can be traded for |

`/oauth/authorize` sends the same names back to the client's `redirect_uri`, with `state`, except when the client or its redirect address cannot be trusted: then it shows a page and sends nothing.

`/oauth/userinfo` and `/oauth/plans` answer `401` with `WWW-Authenticate: Bearer error="invalid_token"` for a token that does not pass.

## Everything else

```json
{ "error": true, "errorCode": "validation.failed", "message": "The request is not valid", "issues": { "name": "name.short" }, "requestId": "..." }
```

| `errorCode` | Means |
|---|---|
| `validation.failed` | The body or query is not valid. `issues` names each field by a code |
| `not_found` | No such thing |
| `auth.missing` | Not signed in, or the caller did not prove itself |
| `auth.code_invalid` | The sign-in code is wrong or has expired |
| `account.suspended` | The account is suspended |
| `rate_limited` | Too many requests. Wait and try again |
| `oauth.client_invalid` | The client or its redirect address cannot be trusted |
| `oauth.unavailable` | Signing is not set up on this server |

## A product's own answers

A product's MCP server answers `401` with `WWW-Authenticate: Bearer error="invalid_token"` for a token that does not pass. The gateway reads a 401 as "trade again" and tries once more; anything else it shows the agent as the product failing.

Source: https://developers.buungroup.com/reference/errors
