Skip to main content
When the middleware rejects a request, it returns a single, stable JSON shape. Because the error_code never changes wording, you can build dashboards and alerts on it with confidence.

​
The codes

​
How to read them at a glance

Group them by who needs to act:
  • 401s — the token is the problem. Usually the agent isn’t sending one, or it expired. If every authenticated call fails the same way, suspect your issuer or audience configuration instead. With the SDK in use, expiry should be auto-refreshed, so a steady stream of EXPIRED_TOKEN is worth investigating (clock skew, a non-SDK caller).
  • 403 MISSING_SCOPE — authentic but not authorized. The agent is who it says it is; it just wasn’t granted that scope. This is an access decision, not a bug — don’t “fix” it by widening scopes reflexively.
  • WRONG_AUDIENCE / WRONG_ISSUER — almost always your config. Set expected_audience to your platform’s canonical resource URI and MUDRAID_EXPECTED_ISSUERS to your environment’s authorization-server issuer. See middleware configuration.
  • 500s — your side, not the agent’s. JWKS_UNAVAILABLE is a connectivity problem reaching MudraID; MIDDLEWARE_NOT_READY is a broken YAML. Neither means the agent did anything wrong.
For V2-mode (ENFORCE_*) codes, see Error responses.

​
What to alert on

  • A spike in JWKS_UNAVAILABLE → connectivity to MudraID is degraded.
  • Any MIDDLEWARE_NOT_READY → you shipped a bad scopes file; page yourself.
  • A spike in MISSING_SCOPE from one agent → it’s trying to do something it wasn’t granted; could be a misconfigured integration or a probe.