Error Codes

Overview

The TrustRails API uses standard HTTP status codes to indicate request outcomes. Every error response includes a machine-readable code field and a human-readable message to help you diagnose and resolve issues quickly.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": "Error Type",
  "message": "A human-readable description of what went wrong",
  "code": "ERROR_CODE"
}

Validation errors include an additional details array with field-level information:

{
  "error": "Validation Error",
  "message": "Invalid request body",
  "details": [
    {
      "code": "invalid_type",
      "path": ["participant", "email"],
      "message": "Expected string, received number"
    }
  ]
}

Rate limit errors include additional fields to help you implement backoff logic:

{
  "error": "Too Many Requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "limit": 1000,
  "remaining": 0,
  "retryAfter": 42
}

HTTP Status Codes

The API uses these HTTP status codes across all endpoints:

Authentication Errors

These errors occur during API key validation before your request reaches the endpoint.

// Example: Missing API key
// HTTP 401
{
  "error": "Unauthorized",
  "message": "API key is required. Include it in the Authorization header as 'Bearer <key>' or in the X-API-Key header.",
  "code": "MISSING_API_KEY"
}

Rate Limit Errors

Rate limits are applied per API key based on your integration tier. Every response includes rate limit headers so you can track your usage proactively.

Rate limit headers are included on every response, not just errors:

X-RateLimit-Limit: 1000        # Your tier's per-minute limit
X-RateLimit-Remaining: 997     # Requests remaining in current window
X-RateLimit-Reset: 1714300800  # Unix timestamp when the window resets
Retry-After: 42                # Seconds to wait (only on 429 responses)

// HTTP 429
{
  "error": "Too Many Requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "limit": 1000,
  "remaining": 0,
  "retryAfter": 42
}

Validation Errors

Request body and query parameter validation errors return a details array with field-level information. These errors use HTTP 400 or 422 depending on the endpoint.

// HTTP 422 - Invalid request body
{
  "error": "Validation Error",
  "message": "Invalid request body",
  "details": [
    {
      "code": "invalid_type",
      "path": ["participant", "email"],
      "message": "Expected string, received number"
    },
    {
      "code": "too_small",
      "path": ["participant", "firstName"],
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

Resource Errors

These errors occur when looking up specific resources like rollovers, partners, or plans.

Rollover Errors

Errors specific to rollover creation, state transitions, and reversals.

Webhook Errors

Errors that can occur when configuring or testing webhooks.

Service Errors

Server-side errors that may require retrying your request.

// HTTP 503 - Maintenance
{
  "error": "Service Unavailable",
  "code": "MAINTENANCE_MODE",
  "requestId": "req_a1b2c3d4",
  "retryAfter": 3600
}

Handling Errors

Best practices for building resilient integrations that handle errors gracefully.

async function apiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.ok) return response.json();
    // Don't retry client errors (except 429)
    if (response.status < 500 && response.status !== 429) {
      const error = await response.json();
      throw new Error(`${error.code}: ${error.message}`);
    }
    if (attempt < maxRetries) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter
        ? parseInt(retryAfter) * 1000
        : Math.min(1000 * 2 ** attempt, 30000) + Math.random() * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Max retries exceeded');
}