Skip to content

Federated Login Internal Error

URI: https://docs.ankatech.co/errors/federation-internal-error
HTTP Status: 502 Bad Gateway

When you see this

A federated login failed on an internal contract between the Auth API and the service it calls to resolve the provider configuration or to provision the identity — not at the identity provider, and not on anything you sent. The upstream call returned something the Auth API could not act on.

The status is a 502 rather than a 500 because the fault is attributed by role: the responding service is fine, the service it depends on is not.

There is deliberately no Retry-After. Retrying cannot clear a contract defect, and the header would restate a false availability claim — which is exactly what once sent an investigation after the identity provider's network path while the real rejection sat one hop away.

Common Causes

  • The upstream service answered with a status or a body the federation client does not accept.
  • A configuration or deployment skew between the Auth API and the service it calls.
  • The upstream is reachable but is refusing the Auth API's own service credential.

Response Example

{
  "type": "https://docs.ankatech.co/errors/federation-internal-error",
  "title": "Federated Login Internal Error",
  "status": 502,
  "detail": "The federated login could not be completed due to an internal platform error. Contact your administrator.",
  "instance": "/api/v3/auth/idp/callback",
  "timestamp": 1730000000
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The Auth API carries no correlation member in the body: correlate through the X-Correlation-Id response header instead. See Error Index & Overview.

The body carries a fixed sentence, never the upstream's own text. This edge is reached by an unauthenticated browser navigation, and the upstream body it describes can carry a decrypted provider secret. The diagnosable cause — the operation and the upstream status — is in the server log only.

How to Resolve

  1. This is not a caller-side failure. Contact your platform administrator rather than changing the request.
  2. For an operator: the Auth API log line names the federation operation and the upstream status against the correlation identifier from the X-Correlation-Id response header.
  3. Confirm the Auth API and the service it calls are on compatible versions and that the S2S credential is accepted.
  4. Local password sign-in is unaffected while this is being resolved.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.