Example
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "An unexpected error occurred while processing your request",
    "status": 500,
    "title": "Internal Server Error",
    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/application/unexpected_error"
  }
}

​
What Happened?

This error occurs when the Unkey system encounters an internal error that wasn’t anticipated or couldn’t be handled gracefully. This is generally not caused by anything you did wrong in your request, but rather indicates an issue within Unkey’s systems. Possible causes of this error:
  • Temporary infrastructure issues
  • Database connectivity problems
  • Bugs in the Unkey service
  • Resource constraints or timeouts
  • Unexpected edge cases not handled by the application logic
Here’s an example of a request that might trigger this error if there’s an internal issue: 
# A valid request that could trigger an unexpected error if there's an internal issue
curl -X POST https://api.unkey.com/v1/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 an internal error, there’s usually little you can do to directly fix it, but you can try the following:
  1. Retry the request: Many unexpected errors are temporary and will resolve on a retry
  2. Check Unkey status: Visit the Unkey status page to see if there are any ongoing service issues
  3. Contact support: If the error persists, contact Unkey support with your request ID
  4. Implement retry logic: For critical operations, implement exponential backoff retry logic in your code
Here’s an example of implementing retry logic with exponential backoff: 
// Pseudocode for retry with exponential backoff
async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 300) {
  let retries = 0;
  while (true) {
    try {
      return await fn();
    } catch (error) {
      if (error.status !== 500 || retries >= maxRetries) {
        throw error; // Either not a 500 error or we've exceeded retries
      }

      // Exponential backoff with jitter
      const delay = baseDelay * Math.pow(2, retries) * (0.8 + Math.random() * 0.4);
      console.log(`Retrying after ${delay}ms (attempt ${retries + 1}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, delay));
      retries++;
    }
  }
}

​
Important Notes

  • Always include the requestId when contacting support about this error
  • This error may indicate a bug in Unkey’s systems that needs to be fixed
  • Unlike most other errors, this one usually can’t be resolved by changing your request
  • If you encounter this error consistently with a specific API call, there may be an edge case that Unkey’s team needs to address