Errors

​

Overview

​

Key Changes in v2:

• Standardized format: All errors use {meta, error} envelope with consistent structure
• Request IDs: Every response includes meta.requestId for debugging
• Enhanced error structure: Errors follow RFC 7807 Problem Details format
• Better debugging: Improved error context and troubleshooting information

​

Error Response Format Changes

​

v1 Error Format → v2 Error Format

// v1 Error Response
{
  "error": { 
    "code": "NOT_FOUND", 
    "message": "Key not found"
  } 
}

// v2 Error Response
{
  "meta": { 
    "requestId": "req_error123abc"
  }, 
  "error": { 
    "title": "Not Found", 
    "detail": "The requested key was not found", 
    "status": 404, 
    "type": "https://unkey.com/docs/errors/unkey/data/key_not_found"
  } 
}

​

Error Code Mapping Table

​

HTTP Status Errors

​

Key Verification Specific Codes

​

Migration Code Examples

// v1: Simple error code checking
const response = await fetch('/v1/keys.verifyKey', { /* ... */ });
const data = await response.json();

if (data.error) {
  switch (data.error.code) {
    case 'NOT_FOUND':
      console.log('Key not found');
      break;
    case 'RATE_LIMITED':
      console.log('Rate limited');
      break;
    default:
      console.log('Unknown error:', data.error.message);
  }
}

// v2: RFC 7807 error handling
const response = await fetch('/v2/keys.verifyKey', { /* ... */ });
const result = await response.json();

if (result.error) {
  const { title, detail, status, type } = result.error;
  const requestId = result.meta.requestId;
  
  // Log for debugging
  console.log(`Error ${status}: ${title} - ${detail} (Request: ${requestId})`);
  
  // Handle by category
  if (type.includes('/authentication/')) {
    console.log('Authentication error');
  } else if (type.includes('/authorization/')) {
    console.log('Authorization error');
  } else if (type.includes('/data/')) {
    console.log('Data error');
  }
}

​

Error Documentation

​

Common Error Categories

• Application Errors: Invalid input, assertion failures, service unavailable
• Authentication Errors: Missing, malformed, or invalid keys
• Authorization Errors: Insufficient permissions, disabled keys, workspace access
• Data Errors: Resource not found, conflicts, data validation issues

​

Error Troubleshooting

• Request IDs: Always include the meta.requestId when contacting support
• Error Types: Use the type URL for detailed documentation about specific errors
• Validation Errors: Check the errors array for field-specific validation failures
• Status Codes: HTTP status codes indicate the general category of the error

​

Common Error Migration Issues

• Errors not being caught properly
• Missing error details that were available in v1
• Unable to determine error type or category

1. Update Error Access Pattern
   Copy

   Ask AI

   // ❌ v1 pattern
   if (response.error) {
     console.log('Error:', response.error.code);
   }
   
   // ✅ v2 pattern
   if (response.error) {
     console.log('Error:', response.error.type);
     console.log('Request ID:', response.meta.requestId);
   }
   

2. Handle New Error Structure
   Copy

   Ask AI

   // v2 error handling with all fields
   if (response.error) {
     const { title, detail, status, type } = response.error;
     
     // Log complete error information
     console.error(`${title} (${status}): ${detail}`);
     console.error(`Error Type: ${type}`);
     console.error(`Request ID: ${response.meta.requestId}`);
     
     // Handle validation errors
     if (response.error.errors) {
       response.error.errors.forEach(err => {
         console.error(`Field ${err.location}: ${err.message}`);
       });
     }
   }
   

3. Error Categorization
   Copy

   Ask AI

   function categorizeError(errorType: string): string {
     if (errorType.includes('/authentication/')) return 'auth';
     if (errorType.includes('/authorization/')) return 'permission';
     if (errorType.includes('/application/')) return 'client';
     if (errorType.includes('/data/')) return 'resource';
     return 'unknown';
   }
   

4. Retry Logic for Retryable Errors
   Copy

   Ask AI

   function isRetryable(errorType: string): boolean {
     return errorType.includes('rate_limited') || 
            errorType.includes('internal_error');
   }
   
   if (response.error && isRetryable(response.error.type)) {
     // Implement retry logic
     setTimeout(() => retryRequest(), 1000);
   }
   

​

Migration Considerations

• Update error parsing to access response.error instead of direct error access
• Extract meta.requestId for logging and support requests
• Handle the new RFC 7807 format with title, detail, status, and type fields
• Process validation errors from the errors array for detailed field-level feedback