> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> ZKScore API error responses and handling

## Overview

ZKScore API returns structured error responses to help you understand and handle issues effectively.

## Error Response Format

All errors follow this structure:

```json theme={null}
{
  "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

| Status | Description           | Action                   |
| ------ | --------------------- | ------------------------ |
| 400    | Bad Request           | Check request parameters |
| 401    | Unauthorized          | Verify API key           |
| 403    | Forbidden             | Check permissions        |
| 404    | Not Found             | Verify resource exists   |
| 429    | Too Many Requests     | Implement backoff        |
| 500    | Internal Server Error | Retry request            |

## Error Handling Examples

<CodeGroup>
  ```javascript JavaScript theme={null}
  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;
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def handle_api_error(response):
      if not response.ok:
          error = response.json()
          
          if error['error']['code'] == 'ZKS-001-001':
              raise ValueError('Identity not found')
          elif error['error']['code'] == 'ZKS-002-001':
              raise ValueError('Invalid API key')
          elif error['error']['code'] == 'ZKS-003-001':
              retry_after = int(response.headers.get('Retry-After', 60))
              time.sleep(retry_after)
          else:
              raise Exception(f"API Error: {error['error']['message']}")
      
      return response
  ```
</CodeGroup>

## 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](/api-reference/rate-limits)
* [Error Codes Reference](/reference/error-codes)