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. 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 — almost always your config. The platform_id in your YAML doesn’t match what MudraID issued tokens for. Re-export the file and redeploy.
  • 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.

​
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.