Guides

Error Handling

Copy page

Verso API uses standard HTTP status codes and returns detailed error responses following the RFC 7807 Problem Details format. This guide explains how to handle errors effectively.

Error Response Format

All error responses follow the Problem Details specification:

Code
 
{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Detailed description of what went wrong",
  "instance": "/payrolls/3/cases",
  "traceId": "00-abc123-def456-00"
}

Field	Description
type	URI reference identifying the error type
title	Short human-readable summary
status	HTTP status code
detail	Detailed explanation of the error
instance	URI of the specific request
traceId	Unique identifier for debugging

HTTP Status Codes

2xx Success

Code	Description
200 OK	Request succeeded, response contains data
201 Created	Resource created successfully
204 No Content	Request succeeded, no response body

4xx Client Errors

Code	Title	Common Causes
400	Bad Request	Invalid JSON, missing required fields, validation errors
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions, tenant mismatch
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate identifier, state conflict
422	Unprocessable Entity	Business logic validation failed
429	Too Many Requests	Rate limit exceeded

5xx Server Errors

Code	Title	Description
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream service unavailable
503	Service Unavailable	Server temporarily unavailable
504	Gateway Timeout	Upstream service timeout

Common Error Scenarios

Validation Errors (400)

Code
 
{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "The 'identifier' field is required",
  "errors": {
    "identifier": ["The identifier field is required."]
  }
}

How to fix:

• Check required fields in your request body
• Validate data types (strings, numbers, dates)
• Ensure JSON is properly formatted

Authentication Errors (401)

Code
 
{
  "type": "https://httpstatuses.com/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

How to fix:

• Verify the Authorization header is present
• Check API key is correctly formatted: Bearer YOUR_API_KEY
• Confirm API key is not expired

Permission Errors (403)

Code
 
{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access denied to division 'Sales'"
}

How to fix:

• Verify you have access to the requested resource
• Check your API key permissions
• Ensure you're operating within your tenant scope

Not Found (404)

Code
 
{
  "type": "https://httpstatuses.com/404",
  "title": "Not Found",
  "status": 404,
  "detail": "Employee with id '999' not found"
}

How to fix:

• Verify the resource ID exists
• Check for typos in the endpoint path
• Ensure the resource belongs to your tenant

Conflict (409)

Code
 
{
  "type": "https://httpstatuses.com/409",
  "title": "Conflict",
  "status": 409,
  "detail": "Employee with identifier '[email protected]' already exists"
}

How to fix:

• Use a unique identifier
• Query existing resources before creating
• Update existing resource instead of creating new

Rate Limiting (429)

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

How to fix:

• Implement exponential backoff
• Respect the retryAfter value
• Cache responses when possible

Error Handling Best Practices

Implement Retry Logic

Retry with Exponential Backoff
 
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }

      if (response.status >= 500) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

Log Error Details

Always log the traceId for debugging:

Error Logging
 
try {
  const response = await api.createEmployee(data);
} catch (error) {
  console.error('API Error:', {
    status: error.status,
    title: error.title,
    detail: error.detail,
    traceId: error.traceId, // Important for support
    instance: error.instance
  });
}

Handle Validation Errors

Display Validation Errors
 
if (response.status === 400 && response.errors) {
  Object.entries(response.errors).forEach(([field, messages]) => {
    console.error(`${field}: ${messages.join(', ')}`);
  });
}

Debugging Tips

Include Trace ID in Support Requests

When contacting support, always include:

• The traceId from the error response
• Timestamp of the request
• The endpoint called
• Request payload (without sensitive data)

Validate Before Sending

Validate your payloads client-side before sending:

Pre-validation
 
function validateEmployee(data) {
  const errors = [];

  if (!data.identifier) {
    errors.push('identifier is required');
  }
  if (!data.firstName) {
    errors.push('firstName is required');
  }
  if (!data.lastName) {
    errors.push('lastName is required');
  }

  return errors;
}

Next Steps

• Authentication - API authentication guide
• Error Codes Reference - Complete error code list
• API Reference - Explore all endpoints