> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudraid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error responses

> The stable error_code contract.

Every error is one JSON shape. Build alerting on it.

```json theme={null}
{
  "error_code": "MISSING_SCOPE",
  "message": "required scope 'items:write' not present in token"
}
```

## The codes

| Status | error\_code            | Cause                                                                             |
| ------ | ---------------------- | --------------------------------------------------------------------------------- |
| 401    | `MISSING_TOKEN`        | `Authorization` header missing or not `Bearer`                                    |
| 401    | `INVALID_TOKEN`        | Malformed JWT or invalid signature                                                |
| 401    | `EXPIRED_TOKEN`        | `exp` is in the past                                                              |
| 401    | `TOKEN_NOT_YET_VALID`  | `nbf` is in the future                                                            |
| 401    | `WRONG_AUDIENCE`       | `aud` doesn't match this platform's `platform_id`                                 |
| 401    | `WRONG_ISSUER`         | `iss` isn't an accepted MudraID issuer (default `mudraid-identity`; configurable) |
| 403    | `MISSING_SCOPE`        | Token valid but required scope absent                                             |
| 404    | `ROUTE_NOT_FOUND`      | No YAML rule, or `skip: true`. Indistinguishable on purpose                       |
| 500    | `JWKS_UNAVAILABLE`     | Couldn't fetch JWKS to verify. Operator-side, not credential-side                 |
| 500    | `MIDDLEWARE_NOT_READY` | YAML couldn't be loaded or parsed                                                 |

Behind this contract: a full unit suite covering every failure shape, the JWKS rotation recovery path, thread safety, and the anti-leak guarantee that no token or secret appears in middleware logs.

For how to act on each code, see [Interpret verification error codes](/guides/platform-operator/error-codes).