Error Handling

The Volunteer API’s error documentation is the sparsest of the three Virtuous APIs. The OpenAPI spec documents error responses on only three of the twenty endpoints (POST /groups, PUT /groups/{id}, PUT /groups/{id}/members — all with a single 422 validation errors). No endpoint formally documents 401, 403, 404, or 500. This gap doesn’t mean those errors don’t occur — they do. It means partner integrations must build defensive error handling without spec guidance about exact response shapes or status codes. This page covers what to expect from the live API, the classification framework that handles each case appropriately, and the patterns that produce reliable production code. ⚠️ Spec gap: The Volunteer OpenAPI spec documents error responses on only three endpoints (all 422 validation errors). The rest of the spec is silent on error responses entirely. The patterns on this page reflect what the live API likely returns based on common REST conventions; confirm against actual responses for production-critical workflows.

What the spec confirms

The three endpoints that do document error responses:

Endpoint	Documented error
`POST /groups`	`422` validation errors
`PUT /groups/{id}`	`422` validation errors
`PUT /groups/{id}/members`	`422` validation errors

Everything else is undocumented. No endpoint exposes the shape of an error response, the fields available on a problem object, or the headers returned with error responses.

What the live API likely returns

Based on common conventions for Laravel-style APIs (which Volunteer appears to be):

HTTP status	When likely returned	Body likely shape
`401 Unauthorized`	Missing, invalid, or expired Bearer token	`{ "message": "Unauthenticated." }` or similar
`403 Forbidden`	Token valid but lacks permission for the resource	`{ "message": "This action is unauthorized." }`
`404 Not Found`	Resource ID doesn’t exist or isn’t accessible	`{ "message": "Resource not found." }`
`422 Unprocessable Entity`	Request body validation failure	`{ "message": "The given data was invalid.", "errors": { "field": ["error message"] } }`
`429 Too Many Requests`	Rate limit exceeded (not documented but possible)	Possibly empty or `{ "message": "Too Many Requests" }`
`500 Internal Server Error`	Server-side bug or unexpected failure	Possibly empty or `{ "message": "Server Error" }`
`503 Service Unavailable`	Maintenance or overload	Possibly empty

These shapes are common in Laravel-based APIs but aren’t formally documented for Volunteer. Don’t switch business logic on specific error message strings — they’re not a contract.

The defensive classification framework

The classifier turns any error response into a category that determines how to handle it:

function classifyError(status, body) {
  // Network or TLS errors (no status)
  if (!status) return 'transient';

  // Success
  if (status >= 200 && status < 300) return 'success';

  // 3xx — typically redirects; treat as transient
  if (status >= 300 && status < 400) return 'transient';

  // Specific 4xx codes
  if (status === 401) return 'auth_failed';
  if (status === 403) return 'forbidden';
  if (status === 404) return 'not_found';
  if (status === 422) return 'validation_failed';
  if (status === 429) return 'rate_limited';

  // Other 4xx — generally not retryable
  if (status >= 400 && status < 500) return 'permanent_client';

  // 5xx — transient server issues
  if (status >= 500) return 'transient';

  return 'unknown';
}

Each classification determines the right response:

Classification	Retry?	Action
`success`	N/A	Use the response.
`auth_failed`	No	Token is bad — pause integration for this customer; alert ops.
`forbidden`	No	Permission issue — alert ops; don’t keep trying.
`not_found`	No	Resource doesn’t exist — return `null` to caller; let them decide.
`validation_failed`	No	Request body has issues — surface field-level errors to user.
`rate_limited`	Yes	Honor `Retry-After` if present; otherwise back off.
`transient`	Yes	Exponential backoff with jitter; bounded attempts.
`permanent_client`	No	Unknown 4xx — log and surface; don’t retry.
`unknown`	No	Log loudly; surface for manual review.

Per-status handling in depth

`401 Unauthorized`: don’t retry

A 401 means the token isn’t being accepted. Common causes:

Cause	Resolution
Token expired (if Volunteer enforces expiration)	Customer’s administrator generates a new token
Token was revoked in the admin portal	Same
Token is malformed in the request (whitespace, missing `Bearer` prefix)	Inspect the actual request — typically a partner-side bug
API access was disabled for the customer’s VOMO account	Customer contacts their VOMO concierge

The response:

if (response.status === 401) {
  await pauseIntegrationForCustomer(customerId, 'auth_failed');
  await alertOps({
    severity: 'high',
    customerId,
    message: 'VOMO token rejected — credential needs refresh',
  });
  throw new AuthError('VOMO token is invalid');
}

Critical: retries against an invalid token just produce more 401s and noise. Pause the customer’s work; alert ops. See Authentication: Handling auth failures.

`403 Forbidden`: also don’t retry

A 403 means the token is valid but doesn’t have permission for the specific endpoint. Causes:

Cause	Resolution
The token’s organization doesn’t have access to the requested resource	The resource belongs to another organization — partner has the wrong token loaded
The customer’s plan doesn’t include the feature	Coordinate with VOMO concierge
The endpoint requires a higher permission tier	Same

if (response.status === 403) {
  await alertOps({
    severity: 'medium',
    customerId,
    endpoint: url,
    message: 'VOMO token lacks permission for this endpoint',
  });
  throw new ForbiddenError(`No permission for ${url}`);
}

Like 401, don’t retry — the permission isn’t going to change in seconds.

`404 Not Found`: handle gracefully

A 404 from a single-resource endpoint (e.g., GET /users/12345) means the user with that ID doesn’t exist in the customer’s organization. Causes:

Cause	Resolution
The ID was wrong	Caller bug
The user was deleted between the integration learning about them and the lookup	Race condition — handle as “not found”
The user exists in a different organization	Partner is using the wrong token
The endpoint doesn’t exist (rare — partner constructed a wrong URL)	Partner-side URL bug

async function getUserById(userId) {
  const response = await fetch(`https://api.vomo.org/v1/users/${userId}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (response.status === 404) {
    return null; // Caller decides what to do
  }

  if (!response.ok) {
    throw await buildError(response);
  }

  return parseUser(await response.json());
}

Don’t retry 404 — a non-existent resource will continue to not exist on retry. Return null and let the caller handle the absence.

`422 Validation Error`: the documented case

The three endpoints that document 422 (POST /groups, PUT /groups/{id}, PUT /groups/{id}/members) return validation errors when the request body doesn’t pass validation. Other endpoints that accept request bodies (POST /projects, POST /users, PUT /projects/{id}) almost certainly return 422 similarly even though it’s undocumented. The body shape (assuming Laravel conventions):

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "email": ["The email must be a valid email address."]
  }
}

Handling:

async function createGroup(groupData) {
  const response = await fetch('https://api.vomo.org/v1/groups', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(groupData),
  });

  if (response.status === 422) {
    const problem = await response.json();
    throw new ValidationError(
      problem.message ?? 'Validation failed',
      problem.errors ?? {}
    );
  }

  if (!response.ok) {
    throw await buildError(response);
  }

  return await response.json();
}

class ValidationError extends Error {
  constructor(message, fieldErrors) {
    super(message);
    this.fieldErrors = fieldErrors; // { fieldName: ["error message", ...] }
  }
}

Don’t retry 422 — the same payload will fail validation again. Surface the field-level errors to the user (or your integration’s logs) so the bad data can be corrected.

`429 Too Many Requests`: rate limited

429 isn’t documented in the spec but rate limits likely exist at the platform level. When it happens:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  const delayMs = retryAfter
    ? parseInt(retryAfter, 10) * 1000
    : 30 * 1000; // Default: 30 seconds

  await sleep(delayMs);
  // Retry the request after the delay
}

See Rate Limits for the broader rate-limit pattern.

`5xx` Server errors: retry with backoff

Server errors (500, 502, 503, 504) are typically transient. Retry with exponential backoff:

async function callWithRetry(fn, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const classification = classifyError(err.status, err.body);

      if (classification !== 'transient' && classification !== 'rate_limited') {
        throw err; // Non-retryable
      }

      if (attempt === maxAttempts) {
        throw err; // Exhausted retries
      }

      const baseDelay = Math.pow(2, attempt - 1) * 1000;
      const jitter = Math.random() * 1000;
      await sleep(baseDelay + jitter);
    }
  }
}

The exponential backoff (1s, 2s, 4s, 8s, 16s with jitter) is the standard pattern. Bounded retries prevent infinite loops; jitter prevents thundering-herd retries from multiple integrations simultaneously.

A complete error-handling pattern

Putting it together as a reusable client:

class VomoApiError extends Error {
  constructor(message, status, body, classification) {
    super(message);
    this.status = status;
    this.body = body;
    this.classification = classification;
  }
}

class VomoClient {
  constructor({ token, customerId, alerter, credentialPause }) {
    this.token = token;
    this.customerId = customerId;
    this.alerter = alerter;
    this.credentialPause = credentialPause;
  }

  async request(path, options = {}) {
    const url = path.startsWith('http') ? path : `https://api.vomo.org/v1${path}`;

    return this._withRetry(async () => {
      const response = await fetch(url, {
        ...options,
        headers: {
          Authorization: `Bearer ${this.token}`,
          Accept: 'application/json',
          ...(options.body ? { 'Content-Type': 'application/json' } : {}),
          ...options.headers,
        },
      });

      if (response.ok) {
        return response.json();
      }

      const body = await this._parseBody(response);
      const classification = classifyError(response.status, body);
      const message = body?.message ?? `Request failed: ${response.status}`;
      const error = new VomoApiError(message, response.status, body, classification);

      // Side effects for specific classifications
      switch (classification) {
        case 'auth_failed':
          await this.credentialPause.pause(this.customerId, 'vomo_auth_failed');
          await this.alerter.send({
            severity: 'high',
            customerId: this.customerId,
            title: 'VOMO token rejected',
            url,
          });
          break;

        case 'forbidden':
          await this.alerter.send({
            severity: 'medium',
            customerId: this.customerId,
            title: 'VOMO permission denied',
            url,
          });
          break;

        case 'rate_limited':
          const retryAfter = response.headers.get('Retry-After');
          error.retryAfter = retryAfter ? parseInt(retryAfter, 10) : null;
          break;
      }

      throw error;
    });
  }

  async _withRetry(fn, maxAttempts = 5) {
    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      try {
        return await fn();
      } catch (err) {
        if (err instanceof VomoApiError) {
          if (err.classification !== 'transient' && err.classification !== 'rate_limited') {
            throw err;
          }
        } else if (!isNetworkError(err)) {
          throw err;
        }

        if (attempt === maxAttempts) throw err;

        const delayMs = err.retryAfter
          ? err.retryAfter * 1000
          : Math.pow(2, attempt - 1) * 1000 + Math.random() * 1000;

        await sleep(delayMs);
      }
    }
  }

  async _parseBody(response) {
    try {
      return await response.json();
    } catch {
      return null;
    }
  }
}

function isNetworkError(err) {
  return ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ECONNREFUSED'].includes(err.code);
}

Usage:

const vomo = new VomoClient({ token, customerId, alerter, credentialPause });

try {
  const user = await vomo.request('/users/12345');
  console.log(user.data);
} catch (err) {
  if (err instanceof VomoApiError) {
    switch (err.classification) {
      case 'not_found':
        return null;
      case 'validation_failed':
        return { errors: err.body.errors };
      default:
        throw err; // Already handled side effects; let it propagate
    }
  }
  throw err;
}

The client centralizes retry, classification, and alerting — caller code only handles the cases it cares about (not_found, validation_failed, etc.).

Surfacing errors meaningfully

The error pattern produces good developer experience when integrated properly:

Don’t swallow errors silently

// ❌ Anti-pattern — caller has no idea what happened
try {
  await fetchUsers();
} catch {
  return [];
}

// ✅ Let errors propagate with context
try {
  return await fetchUsers();
} catch (err) {
  logger.error('User fetch failed', { customerId, error: err.message });
  throw err;
}

Silently returning empty arrays on errors makes problems invisible until they’re catastrophic. Let errors surface so they can be investigated.

Surface field-level validation errors

try {
  await vomo.request('/groups', {
    method: 'POST',
    body: JSON.stringify({ name: 'New Group' }),
  });
} catch (err) {
  if (err.classification === 'validation_failed') {
    // err.body.errors might look like:
    // { name: ["The name has already been taken."] }
    Object.entries(err.body.errors ?? {}).forEach(([field, messages]) => {
      messages.forEach((msg) => {
        ui.showFieldError(field, msg);
      });
    });
    return;
  }
  throw err;
}

Field-level errors are the most useful kind — they tell the user (or the calling code) exactly what’s wrong, not just “something failed.”

Distinguish user-facing from internal errors

function userFacingMessage(err) {
  if (!(err instanceof VomoApiError)) {
    return 'Something went wrong. Please try again.';
  }

  switch (err.classification) {
    case 'auth_failed':
      return 'Our connection to VOMO is having an issue. Our team has been notified.';
    case 'forbidden':
      return 'This action requires additional permission. Contact your administrator.';
    case 'not_found':
      return 'This record could not be found.';
    case 'validation_failed':
      return null; // Field-level errors shown elsewhere
    case 'rate_limited':
      return 'Please wait a moment and try again.';
    case 'transient':
      return 'A temporary issue occurred. Please try again.';
    default:
      return 'Something went wrong. Please try again.';
  }
}

User-facing messages shouldn’t expose technical details (status codes, stack traces, exact error texts from the API). The mapping function above produces friendly messages while preserving the technical details for logs.

Monitoring error rates

Track these metrics for any production Volunteer integration:

Metric	Healthy baseline	Alert threshold
`4xx` rate per customer	<0.5%	>2% sustained
`5xx` rate per customer	<0.1%	>0.5% sustained
`401` rate (any)	0	Any non-zero — credential issue
`429` rate	0 to occasional	Sustained spike — rate-limit issue
`503` rate	0 to occasional	Sustained — VOMO platform issue
Retry success rate	>95%	<80% — transient errors aren’t actually transient

Per-customer breakdowns matter. A customer-specific spike in 401s indicates that customer’s token is bad; a platform-wide spike in 503s indicates a VOMO issue not specific to any one customer.

A common-error-cases checklist

For a new Volunteer integration, walk through these cases explicitly:

Token is invalid (401) → pause customer; alert
Token lacks permission (403) → alert; don’t retry
Resource doesn’t exist (404) → return null; caller decides
Request body invalid (422) → surface field-level errors
Rate limited (429) → honor Retry-After; back off
Server error (5xx) → retry with exponential backoff
Network error → retry as transient
Unexpected 4xx → log and surface; don’t retry
All errors logged with sufficient context (customer ID, endpoint, status, body)
Metrics emitted for each error class
Field-level validation errors surfaced to UI / caller
User-facing messages distinct from internal logs

Where to go next

The retry pattern for 429 responses in detail.The broader recovery patterns — circuit breakers, dead-letter queues, classification.The auth-failure handling section in depth.Error patterns specific to multi-page reads.

Getting Started

Core Concepts

Workflows

Polling and Sync

Recipes

Best Practices

What the spec confirms

What the live API likely returns

The defensive classification framework

Per-status handling in depth

`401 Unauthorized`: don’t retry

`403 Forbidden`: also don’t retry

`404 Not Found`: handle gracefully

`422 Validation Error`: the documented case

`429 Too Many Requests`: rate limited

`5xx` Server errors: retry with backoff

A complete error-handling pattern

Surfacing errors meaningfully

Don’t swallow errors silently

Surface field-level validation errors

Distinguish user-facing from internal errors

Monitoring error rates

A common-error-cases checklist

Where to go next

​What the spec confirms

​What the live API likely returns

​The defensive classification framework

​Per-status handling in depth

​401 Unauthorized: don’t retry

​403 Forbidden: also don’t retry

​404 Not Found: handle gracefully

​422 Validation Error: the documented case

​429 Too Many Requests: rate limited

​5xx Server errors: retry with backoff

​A complete error-handling pattern

​Surfacing errors meaningfully

​Don’t swallow errors silently

​Surface field-level validation errors

​Distinguish user-facing from internal errors

​Monitoring error rates

​A common-error-cases checklist

​Where to go next

What the spec confirms

What the live API likely returns

The defensive classification framework

Per-status handling in depth

`401 Unauthorized`: don’t retry

`403 Forbidden`: also don’t retry

`404 Not Found`: handle gracefully

`422 Validation Error`: the documented case

`429 Too Many Requests`: rate limited

`5xx` Server errors: retry with backoff

A complete error-handling pattern

Surfacing errors meaningfully

Don’t swallow errors silently

Surface field-level validation errors

Distinguish user-facing from internal errors

Monitoring error rates

A common-error-cases checklist

Where to go next