# Error Handling

## Error Response Format

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error message",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ],
    "requestId": "req_abc123"
  }
}
```

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 409 | Conflict |
| 422 | Validation Error |
| 429 | Rate Limited |
| 500 | Internal Error |

## Error Codes

### Authentication Errors

| Code | Description |
|------|-------------|
| `AUTH_INVALID_TOKEN` | Token is invalid or malformed |
| `AUTH_EXPIRED_TOKEN` | Token has expired |
| `AUTH_MISSING_TOKEN` | No token provided |
| `AUTH_INSUFFICIENT_SCOPE` | Token lacks required permissions |

### Validation Errors

| Code | Description |
|------|-------------|
| `VALIDATION_ERROR` | Input validation failed |
| `VALIDATION_REQUIRED` | Required field missing |
| `VALIDATION_FORMAT` | Invalid field format |
| `VALIDATION_RANGE` | Value out of allowed range |

### Resource Errors

| Code | Description |
|------|-------------|
| `RESOURCE_NOT_FOUND` | Requested resource doesn't exist |
| `RESOURCE_CONFLICT` | Resource state conflict |
| `RESOURCE_LOCKED` | Resource is locked |

### Business Logic Errors

| Code | Description |
|------|-------------|
| `APPLICATION_INVALID_STATE` | Action not allowed in current state |
| `DOCUMENT_TYPE_MISMATCH` | Wrong document type |
| `WORKFLOW_ERROR` | Workflow processing error |

## Handling Errors

```javascript
try {
  const result = await client.applications.create(data);
} catch (error) {
  if (error.code === 'VALIDATION_ERROR') {
    // Handle validation errors
    error.details.forEach(d => console.log(`${d.field}: ${d.message}`));
  } else if (error.code === 'AUTH_EXPIRED_TOKEN') {
    // Refresh token and retry
    await client.refreshToken();
    return retry();
  } else {
    // Log and report
    console.error('Unexpected error:', error.requestId);
  }
}
```