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. 
{
  "error_code": "MISSING_SCOPE",
  "message": "required scope 'items:write' not present in token"
}

​
The codes

Statuserror_codeCauseWhose problem
401MISSING_TOKENNo Authorization: Bearer headerAgent
401INVALID_TOKENMalformed JWT or bad signatureAgent
401EXPIRED_TOKENexp is in the pastAgent (SDK should refresh)
401TOKEN_NOT_YET_VALIDnbf is in the futureClock skew
401WRONG_AUDIENCEaud doesn’t match your platform_idYour config
401WRONG_ISSUERiss isn’t an accepted MudraID issuer (default mudraid-identity; configurable)Config, or an attack
403MISSING_SCOPEToken valid, but lacks the route’s scopeAgent not granted it
404ROUTE_NOT_FOUNDNo rule for the route, or skip: trueBy design
500JWKS_UNAVAILABLECouldn’t fetch MudraID’s keys to verifyOperator / network
500MIDDLEWARE_NOT_READYYAML couldn’t be loaded or parsedOperator

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