Errors

rIDM answers errors in the format each protocol expects, so a client library written for that protocol understands them without special handling:

The types are defined in api/src/error.rs.

OAuth and OIDC errors

Token, PAR, device-authorization, introspection and revocation errors are JSON with Cache-Control: no-store:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{"error": "invalid_grant", "error_description": "invalid authorization code"}

invalid_client answers 401 with WWW-Authenticate: Basic realm="ridm". The codes rIDM emits:

A rate-limited OAuth request answers 429 with {"error": "slow_down", "error_description": "too many requests; retry after N seconds"} and Retry-After (see Rate limits).

Dynamic client registration

/register and /register/{client_id} (RFC 7591, RFC 7592) use the same JSON shape with the registration codes: invalid_redirect_uri and invalid_client_metadata (400), access_denied (403, registration disabled for the tenant), and invalid_token with a Bearer challenge (401) when an initial access token (under dcr.mode: initial_access_token) or a registration access token is missing, unknown, revoked, expired or used up.

Authorization endpoint

/authorize follows the order RFC 6749 §4.1.2.1 requires. Problems found before the redirect URI can be trusted are shown to the user as an HTML page with the code and description, because redirecting would send the browser somewhere unverified:

Every other error returns to the client’s redirect URI in the requested response mode, with error, error_description, state and iss (RFC 9207):

https://app.example.com/callback?error=login_required&error_description=...&state=af0ifjsldkj&iss=https%3A%2F%2Fid.example.com%2Ft%2Facme

Bearer token errors (RFC 6750)

/userinfo refuses a bad access token with a challenge and a JSON body:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="access token is invalid or expired"
Cache-Control: no-store

{"error": "invalid_token", "error_description": "access token is invalid or expired"}

A DPoP-bound token presented as a plain bearer token, without a proof or with another key’s proof answers 401 with a challenge naming both schemes and the accepted proof algorithms (RFC 9449 §7.1):

WWW-Authenticate: DPoP error="invalid_token", error_description="...", algs="ES256 ES384 RS256 RS384 RS512 PS256 PS384 PS512 EdDSA", Bearer error="invalid_token"

ridm-auth

The ridm-auth crate answers the same way on your own API. Its AuthError keeps “not acceptable” (401), “not enough” (403) and “could not check” (503) apart, because a caller that cannot tell them apart cannot retry correctly:

The realm defaults to api. AuthError::is_transient() is true only for the 503 family. Every response carries Cache-Control: no-store.

ridm-auth validates JWT access tokens only. An opaque at_… token, issued to a client registered with access_token_format: opaque, is refused as a malformed token (401 invalid_token); an API that must accept those checks them at /introspect instead.

Problem documents (RFC 9457)

The admin API, the account API, the flow API, recovery, verification, invitations and device verification answer errors as application/problem+json:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "urn:ridm:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "missing permission `ridm:users:write`"
}

Admin and account API 401 responses also carry WWW-Authenticate: Bearer realm="ridm-admin" (with error="invalid_token" when a token was presented but refused) and Cache-Control: no-store. The account API shares the admin API’s realm.

Reauthentication required

Security changes in the account API (second factors, the password, contact details, linked identities, trusted devices, sessions, personal access tokens, deleting the account) need a sign-in from the last 15 minutes, and with a second factor once the account has one. Otherwise:

{
  "type": "urn:ridm:error:reauthentication-required",
  "title": "Forbidden",
  "status": 403,
  "detail": "sign in again with your second step to change security settings"
}

The client re-authorizes with max_age=0 (and an MFA class in acr_values when the detail asks for the second step) and retries with the new token.

Flow API

Problems in the flow API use the same types; CAPTCHA enforcement reports validation with {"field": "captcha_token", "message": "captcha_required"} or "captcha_failed". A refused credential is not a problem document but a plain 401 the sign-in page shows inline, carrying the flow’s failed-attempt count:

{"error": "invalid_credentials", "error_description": "incorrect identifier or password", "attempts": 2}

SCIM errors

The SCIM endpoints answer RFC 7644 §3.12 error documents as application/scim+json:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidFilter",
  "detail": "unexpected token at position 14"
}

scimType is one of invalidFilter, invalidSyntax, invalidPath, invalidValue, noTarget, uniqueness (409) and tooMany (a non-indexed user filter over more than 2,000 users, or startIndex beyond 2,000). A missing or invalid provisioning token is 401 with WWW-Authenticate: Bearer realm="scim".

Adding members to a group whose roles grant any ridm:* admin permission is 403 with no scimType (RFC 7644 defines none for an operation the credentials do not permit), and nothing is changed; see SCIM provisioning.

Rate limits

The OAuth, authorization and flow endpoint families are rate limited (see Rate limits, IP rules and CAPTCHA). Every response of a limited family carries the tightest bucket’s state:

RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 42
Retry-After: 42

A refused request is 429 with Retry-After in seconds, rendered in the family’s own format:

A tenant IP rule that refuses the address is 403 in the same three formats (access_denied for OAuth and HTML, urn:ridm:error:forbidden for problems). If Valkey is unreachable the limiter fails open with a warning in the log; the IP-rule check fails closed (503).