Error Handling

​

Overview

​

Error Response Format

{
  "error": {
    "code": "ZKS-001-001",
    "message": "Identity not found",
    "details": "The requested ZKS ID does not exist",
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_123456789"
  }
}

​

Common Error Codes

​

Identity Errors (ZKS-001-xxx)

• ZKS-001-001: Identity not found
• ZKS-001-002: Identity not activated
• ZKS-001-003: Invalid ZKS ID format

​

Authentication Errors (ZKS-002-xxx)

• ZKS-002-001: Invalid API key
• ZKS-002-002: API key expired
• ZKS-002-003: Insufficient permissions

​

Rate Limit Errors (ZKS-003-xxx)

• ZKS-003-001: Rate limit exceeded
• ZKS-003-002: Quota exceeded

​

Score Errors (ZKS-004-xxx)

• ZKS-004-001: Score not found
• ZKS-004-002: Score calculation failed

​

HTTP Status Codes

​

Error Handling Examples

async function handleApiError(response) {
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.error.code) {
      case 'ZKS-001-001':
        throw new Error('Identity not found');
      case 'ZKS-002-001':
        throw new Error('Invalid API key');
      case 'ZKS-003-001':
        const retryAfter = response.headers.get('Retry-After');
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        break;
      default:
        throw new Error(`API Error: ${error.error.message}`);
    }
  }
  
  return response;
}

​

Best Practices

1. Always Check Status Codes: Verify response status before processing
2. Implement Retry Logic: Handle temporary failures gracefully
3. Log Error Details: Include request IDs for debugging
4. Handle Rate Limits: Implement exponential backoff
5. Validate Inputs: Prevent errors before making requests

​

Related Documentation

• Rate Limits
• Error Codes Reference