Search

Error Handling Reference

Understanding how to handle errors is critical for building reliable integrations. The CCM API returns structured error responses and HTTP status codes that allow precise error handling.

Error Response Structure

All error responses (4xx and 5xx) return a consistent JSON body:

{
  "message": "Descriptive error message",
  "type": "ERROR_TYPE_CONSTANT",
  "timestamp": "2025-04-23T10:30:00"
}
Error Type Reference
Error Type HTTP Status Description
SYSTEM 500 Unexpected server error. Log the timestamp and contact support.
VALIDATION 400 Request body failed validation constraints.
NOT_FOUND 404 The requested resource does not exist.
CONFLICT 409 A conflicting operation is already in progress (e.g., scan running).
BAD_REQUEST 400 Malformed or semantically invalid request parameters.
Multi-Status Handling

The Websites endpoints support batch operations. When requests contain multiple URLs, some may succeed while others fail. The API signals this with HTTP 207 Multi-Status. Consumers should always iterate over every result object:

// JavaScript — handle multi-status
function processResults(results, successStatus) {
  const successes = results.filter(r => r.status === 'SUCCESS');
  const failures  = results.filter(r => r.status !== 'SUCCESS');

  if (failures.length > 0) {
    console.warn('Some operations failed:');
    failures.forEach(f => console.warn(` - ${f.url}: ${f.message}`));
  }
  return { successes, failures };
}
Retry Guidance
Status Code Retryable? Recommendation
400 No Fix the request payload before retrying.
401 After re-auth Obtain a new token, then retry.
403 No Contact your admin to verify role assignment.
404 No Verify the resource exists before retrying.
409 Yes (backoff) Wait for the conflicting operation to complete, then retry with exponential backoff.
500 Yes (backoff) Use exponential backoff starting at 2s. Contact support if error persists.
TrustArc  ·  CCM External API  ·  https://trustarc.com/