Reference

Error Codes Reference

Copy page

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	Rate limit exceeded	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:

Code
 
{
  "type": "https://httpstatuses.com/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:

Code
 
{
  "type": "https://httpstatuses.com/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:

Code
 
{
  "type": "https://httpstatuses.com/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:

Code
 
{
  "type": "https://httpstatuses.com/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:

Code
 
{
  "type": "https://httpstatuses.com/409",
  "title": "Conflict",
  "status": 409,
  "detail": "Employee with identifier '[email protected]' 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:

Code
 
{
  "type": "https://httpstatuses.com/422",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Employee '[email protected]' is not assigned to division 'Sales'"
}

Rate Limiting (429)

Response Headers:

Code
 
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200

Example Response:

Code
 
{
  "type": "https://httpstatuses.com/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Try again in 60 seconds",
  "retryAfter": 60
}

Resolution:

1. Implement exponential backoff
2. Respect Retry-After header
3. Cache responses when possible
4. Contact support for higher limits

Server Errors (5xx)

Internal Server Error (500)

Code
 
{
  "type": "https://httpstatuses.com/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)

Code
 
{
  "type": "https://httpstatuses.com/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 - Handling strategies
• Authentication - Auth troubleshooting
• API Reference - All endpoints