service_unavailable

err:unkey:application:service_unavailable

Example

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "The service is temporarily unavailable. Please try again later.",
    "status": 503,
    "title": "Service Unavailable",
    "type": "https://unkey.com/docs/errors/unkey/application/service_unavailable"
  }
}

What Happened?

This error occurs when a component of the Unkey platform is temporarily unavailable or unable to process your request. Unlike an unexpected error, this is a known state where the system has detected that it cannot currently provide the requested service. Possible causes of this error:

Scheduled maintenance
High load or capacity issues
Dependent service outages
Regional infrastructure problems
Database overload or maintenance

Here’s an example of a request that might receive this error during a service disruption:

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "apiId": "api_123abc",
    "name": "My API Key"
  }'

How To Fix

Since this is a temporary service issue, the best approach is to wait and retry. Here are some strategies:

Implement retry logic: Add automatic retries with exponential backoff to your code
Check service status: Visit the Unkey status page for updates on service availability
Try alternate regions: If Unkey offers region-specific endpoints, try an alternate region
Wait and retry manually: If it’s a one-time operation, simply try again later

Here’s an example of a robust retry strategy:

# Bash script with retry logic
max_attempts=5
attempt=0
backoff_time=1

while [ $attempt -lt $max_attempts ]; do
  response=$(curl -s -w "\n%{http_code}" \
    -X POST https://api.unkey.com/v2/keys.createKey \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer unkey_YOUR_API_KEY" \
    -d '{
      "apiId": "api_123abc",
      "name": "My API Key"
    }')

  http_code=$(echo "$response" | tail -n1)
  body=$(echo "$response" | sed '$ d')

  if [ $http_code -eq 503 ]; then
    attempt=$((attempt+1))
    if [ $attempt -eq $max_attempts ]; then
      echo "Service still unavailable after $max_attempts attempts"
      exit 1
    fi

    echo "Service unavailable, retrying in $backoff_time seconds... (Attempt $attempt/$max_attempts)"
    sleep $backoff_time
    backoff_time=$((backoff_time*2))
  else
    echo "$body"
    exit 0
  fi
done

Important Notes

This error is temporary, and the service will typically recover automatically
For critical applications, implement circuit breakers to prevent cascading failures
If the service remains unavailable for an extended period, check Unkey’s status page or contact support
Include the requestId from the error response when contacting support

err:unkey:application:unexpected_error - When an unhandled error occurs
err:unkey:authorization:workspace_disabled - When the workspace is disabled (a different type of unavailability)

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

What Happened?

How To Fix

Important Notes

​What Happened?

​How To Fix

​Important Notes

​Related Errors

What Happened?

How To Fix

Important Notes

Related Errors