Error Handling

All CRM+ API errors return JSON with a consistent structure — most of the time. HTTP status codes indicate the general category of failure; the response body provides machine-readable codes and human-readable descriptions. A small number of endpoints still return plain-text error bodies in legacy formats, so robust integrations always inspect response.status first before parsing the body. This page covers the canonical error shape, every standard HTTP status code, and a worked example of defensive client code.

Target error shape

The canonical error response the CRM+ API is moving toward is:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request body contains invalid values.",
    "details": [
      {
        "field": "giftAmount",
        "code": "MUST_BE_POSITIVE",
        "message": "Gift amount must be greater than zero."
      },
      {
        "field": "giftDate",
        "code": "REQUIRED",
        "message": "Gift date is required."
      }
    ]
  }
}

Field	Type	Description
`error.code`	`string`	Machine-readable error code in `SCREAMING_SNAKE_CASE`. Safe to use in `switch` statements.
`error.message`	`string`	Human-readable explanation, safe to log. Never contains stack traces or database error text.
`error.details`	`array`	Field-level validation errors. Present as an empty array `[]` when no field-specific errors apply.
`error.details[].field`	`string`	The camelCase field name that failed validation.
`error.details[].code`	`string`	Machine-readable `SCREAMING_SNAKE_CASE` code for this specific field failure.
`error.details[].message`	`string`	Human-readable description of this specific validation failure.

The CRM+ API is in the process of migrating to this canonical shape. Some endpoints currently return plain-text error messages or non-standard JSON structures — particularly for 401 Unauthorized responses, which may return Authorization has been denied for this request. as plain text. Write your error handling to inspect response.status first, then attempt to parse the body. Do not assume the body is always valid JSON or always matches the canonical shape.

The CRM+ spec does not yet document 401, 403, 422, 429, or 500 responses on any individual endpoint. These errors can and do occur. Build your integration to handle all standard HTTP error codes defensively, not just the ones explicitly listed in the reference documentation.

Standard error codes

HTTP Status	Code	Meaning	Common causes
`400`	`BAD_REQUEST`	Malformed request	Invalid JSON syntax, missing required headers, unparseable request body
`401`	`UNAUTHENTICATED`	Authentication failed	Missing `Authorization` header, expired OAuth token, revoked API Key
`403`	`FORBIDDEN`	Authorization failed	Valid credentials but insufficient permissions for this resource or action
`404`	`NOT_FOUND`	Resource not found	The ID in the path does not match any existing record
`409`	`CONFLICT`	State conflict	Duplicate record, uniqueness constraint violation
`422`	`VALIDATION_FAILED`	Semantic validation failed	Valid JSON syntax but a field value violates a business rule (e.g., negative gift amount, future gift date on a completed gift)
`429`	`RATE_LIMITED`	Rate limit exceeded	More than 1,500 requests in the current hour — see Rate Limits
`500`	`INTERNAL_ERROR`	Server error	Unexpected error on the Virtuous side — not caused by the request
`503`	`SERVICE_UNAVAILABLE`	Service unavailable	Temporary outage — retry after the period indicated in the `Retry-After` header

404 means the specific resource does not exist. An empty search result on a list endpoint is not a 404 — it returns 200 with list: [] and total: 0. Code that treats 404 as “no records matched” will misinterpret real missing-resource errors.

Handling errors in code

A production-grade CRM+ client should: inspect the status before parsing the body, fall back gracefully when the body is plain text, branch on status for actionable error types, and respect the Retry-After header on 429.

# Check the HTTP status code and inspect the body on error
RESPONSE=$(curl -s -o /tmp/response_body.json -w "%{http_code}" \
  -X POST https://api.virtuoussoftware.com/api/Gift \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contactId": 4821, "amount": -50}')

if [ "$RESPONSE" -ge 400 ]; then
  echo "Error $RESPONSE:"
  cat /tmp/response_body.json
fi

async function callCrmApi(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      Authorization: `Bearer ${process.env.VIRTUOUS_API_TOKEN}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  // Always attempt to parse JSON — but handle plain-text fallback
  let body;
  const contentType = response.headers.get('content-type') || '';
  if (contentType.includes('application/json')) {
    body = await response.json();
  } else {
    body = { error: { code: 'UNKNOWN', message: await response.text() } };
  }

  if (!response.ok) {
    const error = body?.error || {};
    switch (response.status) {
      case 400:
        throw new Error(`Bad request: ${error.message}`);
      case 401:
        throw new Error('Authentication failed — check your API token.');
      case 403:
        throw new Error('Permission denied for this resource.');
      case 404:
        throw new Error(`Resource not found: ${error.message}`);
      case 422: {
        const fieldErrors = (error.details || [])
          .map((d) => `${d.field}: ${d.message}`)
          .join(', ');
        throw new Error(`Validation failed: ${fieldErrors}`);
      }
      case 429: {
        // Respect the Retry-After header — see Rate Limits page
        const retryAfter = response.headers.get('Retry-After') || '60';
        throw new Error(`Rate limited — retry after ${retryAfter}s`);
      }
      default:
        throw new Error(`API error ${response.status}: ${error.message}`);
    }
  }

  return body;
}

Validation error details

When the API returns 422 VALIDATION_FAILED, the error.details array contains one entry per field that failed validation. Use these entries to surface specific error messages to your users or to identify the exact field that needs correction.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request body contains invalid values.",
    "details": [
      {
        "field": "amount",
        "code": "MUST_BE_POSITIVE",
        "message": "Gift amount must be greater than zero."
      },
      {
        "field": "giftDate",
        "code": "REQUIRED",
        "message": "Gift date is required."
      }
    ]
  }
}

When error.details is an empty array ([]), the error applies to the request as a whole, not to any specific field.

Surface error.details[].message directly to end users in your integration’s UI. The messages are written for human consumption and do not leak internal system details. Use error.details[].code for programmatic branching (for example, to retry differently for a REQUIRED field versus a MUST_BE_POSITIVE value).

Retryable vs. non-retryable errors

Not every error is worth retrying. Categorize errors before deciding whether to retry:

Category	Status codes	Retry?	Notes
Transient	`429`, `500`, `502`, `503`, `504`	Yes — with backoff	Respect the `Retry-After` header on `429` and `503`.
Authentication	`401`	Only after refreshing the credential	For OAuth, attempt one refresh and one retry. For API Keys, do not retry — the key has been revoked.
Authorization	`403`	No	The credential lacks the required permission. Retrying with the same credential will fail again.
Client error	`400`, `404`, `409`, `422`	No	The request needs to change. Retrying the identical request will produce the identical error.

See Rate Limits for the canonical retry-with-backoff pattern for 429 responses.

Cross-API error handling

If your integration uses both Raise and CRM+, note that the two APIs return different error shapes. CRM+ uses an error.code / error.message / error.details[] envelope. Raise uses an RFC 7807–style title / status / detail envelope with field-level errors in a flat errors map.

Product	Top-level error fields	Validation details
CRM+	`error.code`, `error.message`, `error.details[]`	`error.details[].field`, `error.details[].code`, `error.details[].message`
Raise	`title`, `status`, `detail`	`errors.{fieldName}[]`

Detect which shape you have by checking whether the response root contains error (CRM+) or title (Raise). See Raise Error Handling for the Raise-specific details.

Next steps

Rate Limits

The retry-with-backoff pattern for handling 429 Too Many Requests responses.

Pagination and Filtering

How to iterate large result sets and how empty-result responses differ from 404.

Authentication

How to fix 401 and 403 responses by checking credentials and permission groups.

Reconcile Failed Syncs

Patterns for retrying, deduplicating, and recovering from partial failures in bulk operations.

Getting Started

Core Concepts

Workflows

Webhooks

Recipes

Best Practices

Target error shape

Standard error codes

Handling errors in code

Validation error details

Retryable vs. non-retryable errors

Cross-API error handling

Next steps

Rate Limits

Pagination and Filtering

Authentication

Reconcile Failed Syncs

​Target error shape

​Standard error codes

​Handling errors in code

​Validation error details

​Retryable vs. non-retryable errors

​Cross-API error handling

​Next steps

Rate Limits

Pagination and Filtering

Authentication

Reconcile Failed Syncs

Target error shape

Standard error codes

Handling errors in code

Validation error details

Retryable vs. non-retryable errors

Cross-API error handling

Next steps