Skip to content

Temporarily Unavailable

URI: https://docs.ankatech.co/errors/temporarily_unavailable
HTTP Status: 503 Service Unavailable

This error also corresponds to the RFC 6749 OAuth 2.0 error code temporarily_unavailable of the same name. The RFC 9457 type suffix uses the identical underscore form so the two identifiers match.

When you see this

POST /api/v3/auth/token shed the request because the concurrent credential-verification bound was reached. The bound is server-wide: the service is momentarily at capacity, whoever is asking. It is protecting itself from a burst it cannot verify in parallel, and it sheds the request before the credential is examined, so this answer says nothing about whether your credential is valid.

The status is 503 because this is a temporary overload of the server (RFC 9110 §15.6.4), not a statement about your request rate. RFC 6749 §4.1.2.1 defines temporarily_unavailable as exactly this condition. A per-caller rate limit is a different refusal: 429 too-many-requests.

The response carries Retry-After: 1. Applies to the password and client_credentials grants.

Common Causes

  • A burst of concurrent token requests from one or more clients.
  • A client retrying aggressively without honouring Retry-After, which sustains the very condition it is retrying into.
  • Many workloads starting at once and all authenticating in the same instant.

Response Example

This endpoint emits the dual-format OAuth body: the RFC 6749 members alongside the RFC 9457 ones.

{
  "error": "temporarily_unavailable",
  "error_description": "The server is temporarily unable to verify client credentials. Retry shortly.",
  "error_uri": "https://docs.ankatech.co/errors/temporarily_unavailable",
  "type": "https://docs.ankatech.co/errors/temporarily_unavailable",
  "title": "Temporarily Unavailable",
  "status": 503,
  "detail": "The server is temporarily unable to verify client credentials. Retry shortly.",
  "instance": "/api/v3/auth/token",
  "timestamp": 1730000000
}

Content-Type: application/problem+json. The body carries the RFC 9457 members, so the media type declares them; the RFC 6749 members ride alongside for OAuth clients that switch on error. Switch on the status and the error member.

The Auth API carries no correlation member in the body: correlate through the X-Correlation-Id response header instead. See Error Index & Overview.

How to Resolve

  1. Honour Retry-After and retry. The condition is transient by construction.
  2. Back off exponentially, with jitter, on repeated occurrences rather than retrying at a fixed interval.
  3. Cache and reuse access tokens until they are close to expiry instead of requesting one per call.
  4. Stagger the start-up of workloads that would otherwise authenticate simultaneously.

The Java SDK's token sources already treat this response as back-pressure: they wait for Retry-After and retry, and never report it as a credential failure.

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