# Error Codes Reference

This reference documents all error codes returned by the Verso API. Use this guide to understand and resolve errors in your integration.

## HTTP Status Codes

### Success Codes (2xx)

| Code | Name | Description |
|------|------|-------------|
| `200` | OK | Request succeeded |
| `201` | Created | Resource created successfully |
| `204` | No Content | Request succeeded, no content returned |

### Client Error Codes (4xx)

| Code | Name | Description | Resolution |
|------|------|-------------|------------|
| `400` | Bad Request | Invalid request format or validation error | Check request body and parameters |
| `401` | Unauthorized | Missing or invalid authentication | Verify API key |
| `403` | Forbidden | Insufficient permissions | Check access rights |
| `404` | Not Found | Resource doesn't exist | Verify resource ID |
| `405` | Method Not Allowed | HTTP method not supported | Use correct HTTP method |
| `409` | Conflict | Resource state conflict | Resolve duplicate or state issue |
| `415` | Unsupported Media Type | Invalid content type | Use `application/json` |
| `422` | Unprocessable Entity | Business validation failed | Fix business logic errors |
| `429` | Too Many Requests | Too many requests in short period | Implement backoff and retry |

### Server Error Codes (5xx)

| Code | Name | Description | Resolution |
|------|------|-------------|------------|
| `500` | Internal Server Error | Unexpected server error | Retry or contact support |
| `502` | Bad Gateway | Upstream service error | Retry later |
| `503` | Service Unavailable | Service temporarily down | Retry later |
| `504` | Gateway Timeout | Request timeout | Retry with smaller payload |

## Validation Errors (400)

### Request Body Errors

| Error | Description | Example |
|-------|-------------|---------|
| `required_field` | Missing required field | `"identifier" is required` |
| `invalid_type` | Wrong data type | `Expected number, got string` |
| `invalid_format` | Invalid format | `Invalid date format` |
| `invalid_value` | Value out of range | `tauxPAS must be between 0 and 1` |
| `invalid_json` | Malformed JSON | `Unexpected token at position 42` |

**Example Response:**
```json
{
  "type": "https://httpproblems.com/http-status/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more validation errors occurred",
  "errors": {
    "identifier": ["The identifier field is required."],
    "tauxPAS": ["The field tauxPAS must be between 0 and 1."]
  }
}
```

### Query Parameter Errors

| Error | Description | Example |
|-------|-------------|---------|
| `invalid_filter` | Invalid filter syntax | `Invalid filter expression` |
| `invalid_orderby` | Invalid orderby field | `Cannot order by 'unknownField'` |
| `invalid_top` | Invalid pagination value | `top must be positive` |

## Authentication Errors (401)

| Error Code | Description | Resolution |
|------------|-------------|------------|
| `missing_auth` | No Authorization header | Add `Authorization: Bearer YOUR_KEY` |
| `invalid_token` | Malformed token | Check token format |
| `expired_token` | Token expired | Request new credentials |
| `invalid_key` | API key not recognized | Verify API key |

**Example Response:**
```json
{
  "type": "https://httpproblems.com/http-status/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}
```

## Permission Errors (403)

| Error Code | Description | Resolution |
|------------|-------------|------------|
| `tenant_mismatch` | Resource belongs to another tenant | Use correct tenant credentials |
| `division_access` | No access to division | Request division access |
| `insufficient_permissions` | Action not permitted | Contact administrator |

**Example Response:**
```json
{
  "type": "https://httpproblems.com/http-status/403",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access denied to division 'Sales'"
}
```

## Resource Errors (404)

| Error Code | Description | Resolution |
|------------|-------------|------------|
| `user_not_found` | User doesn't exist | Verify user ID |
| `employee_not_found` | Employee doesn't exist | Verify employee ID |
| `payroll_not_found` | Payroll doesn't exist | Verify payroll ID |
| `division_not_found` | Division doesn't exist | Verify division name |
| `payrun_not_found` | Payrun job doesn't exist | Verify payrun job ID |

**Example Response:**
```json
{
  "type": "https://httpproblems.com/http-status/404",
  "title": "Not Found",
  "status": 404,
  "detail": "Employee with id '999' not found"
}
```

## Conflict Errors (409)

| Error Code | Description | Resolution |
|------------|-------------|------------|
| `duplicate_identifier` | Identifier already exists | Use unique identifier |
| `duplicate_email` | Email already registered | Use different email |
| `state_conflict` | Invalid state transition | Check resource state |
| `concurrent_modification` | Resource was modified | Retry with fresh data |

**Example Response:**
```json
{
  "type": "https://httpproblems.com/http-status/409",
  "title": "Conflict",
  "status": 409,
  "detail": "Employee with identifier 'john@company.com' already exists"
}
```

## Business Logic Errors (422)

| Error Code | Description | Resolution |
|------------|-------------|------------|
| `invalid_period` | Invalid payroll period | Check date range |
| `employee_not_in_division` | Employee not in specified division | Verify division assignment |
| `payrun_already_complete` | Cannot modify completed payrun | Create new payrun |
| `invalid_forecast` | Invalid forecast identifier | Check forecast format |

**Example Response:**
```json
{
  "type": "https://httpproblems.com/http-status/422",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Employee 'jean.dupont@company.com' is not assigned to division 'Sales'"
}
```

## Server Errors (5xx)

### Internal Server Error (500)

```json
{
  "type": "https://httpproblems.com/http-status/500",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred",
  "traceId": "00-abc123def456-789ghi-00"
}
```

**Resolution:**
1. Note the `traceId` for support
2. Retry the request
3. Contact support if persistent

### Service Unavailable (503)

```json
{
  "type": "https://httpproblems.com/http-status/503",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Service temporarily unavailable for maintenance",
  "retryAfter": 300
}
```

**Resolution:**
1. Wait for `retryAfter` seconds
2. Implement retry logic
3. Check status page for updates

## Getting Help

When contacting support, include:

1. **Trace ID**: The `traceId` from the error response
2. **Timestamp**: When the error occurred
3. **Endpoint**: The API endpoint called
4. **Request**: The request payload (sanitized)
5. **Response**: The complete error response

## Next Steps

- [Error Handling](/guides/error-handling) - Handling strategies
- [Authentication](/authentication) - Auth troubleshooting
- [API Reference](/api) - All endpoints