Error model & rate limiting

Scan2Evolve returns structured error payloads so you can distinguish retryable incidents from permanent validation issues. Implement exponential backoff for 429 responses.

Error Response Format

Error responses follow a simple structure. For validation and request errors:

{
  "error": "employees array is required",
  "requestId": "sync-1234567890-abc123"
}

For batch operations (like Employee Sync), errors are included in the response alongside results:

{
  "syncBatchId": "batch-001",
  "results": [
    {
      "externalEmployeeId": "EMP-001",
      "status": "CREATED",
      "employeeId": "emp_abc123...",
      "warnings": []
    }
  ],
  "errors": [
    {
      "externalEmployeeId": "EMP-002",
      "message": "externalEmployeeId is required"
    }
  ]
}

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request succeeded. Response body contains the requested data.
400	Bad Request	Request is malformed or missing required fields. Check the error details.
401	Unauthorized	Authentication failed. Check your API credentials or token.
403	Forbidden	You don't have permission to access this resource.
404	Not Found	The requested resource doesn't exist.
429	Too Many Requests	Rate limit exceeded. Implement exponential backoff and retry.
500	Internal Server Error	An unexpected error occurred. Contact support if this persists.

Rate Limiting

Rate Limit Policy

To ensure fair usage and system stability, the API enforces rate limits:

100 requests per minute per API key
1000 requests per hour per API key
Rate limit headers are included in all responses

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1638360000

Header Descriptions:

X-RateLimit-Limit: Maximum number of requests allowed in the current window
X-RateLimit-Remaining: Number of requests remaining in the current window
X-RateLimit-Reset: Unix timestamp when the rate limit window resets

Handling Rate Limits

When you receive a 429 Too Many Requests response:

Check the X-RateLimit-Reset header to determine when to retry
Implement exponential backoff: wait 1s, then 2s, then 4s, etc.
Respect the Retry-After header if present
Consider batching requests to reduce API calls

Updated 1 day ago

Date/Time Format