Skip to content

Temporarily Unavailable

URI: https://docs.ankatech.co/errors/temporarily_unavailable
HTTP Status: 429 Too Many Requests

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 proof-verification bound was reached. The service is healthy; it is protecting itself from a burst it cannot verify in parallel.

RFC 6749 defines no error code for back-pressure. temporarily_unavailable (§4.1.2.1) is the closest defined value and is what a client that switches on the error field will handle correctly; the status is what actually carries the meaning here.

The response carries Retry-After: 1.

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": 429,
  "detail": "The server is temporarily unable to verify client credentials. Retry shortly.",
  "instance": "/api/v3/auth/token",
  "timestamp": 1730000000
}

Content-Type: application/json — not application/problem+json. RFC 6749 §5.2 defines the token endpoint's error response, and the Auth API emits that shape deliberately: the RFC 9457 members ride along for clients that read them, but no RFC 9457 media type or envelope is emitted on this endpoint. Switch on the status and the error member, never on the media type.

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 once. The condition is transient by construction.
  2. Back off exponentially 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.

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