Error Handling

Understand error responses and how to handle them effectively.

Error Response Structure

All error responses from the ImpactAPI follow a consistent structure:

Standard Error Format

{
  "error": {
    "code": "error.code_name",
    "message": "Human-readable error message",
    "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      // Optional: Additional context about the error
    }
  }
}

The details object is optional and contains additional context specific to the error type.

Correlation IDs

Tracking Errors

Each error response includes a correlation_id (UUID format) that uniquely identifies the request. Use this ID when contacting support for faster debugging.

Pro tip: Log correlation IDs in your application for easier troubleshooting.

HTTP Status Codes

The ImpactAPI uses standard HTTP status codes:

401Unauthorized

The API key is missing, invalid, or has been revoked.

{
  "error": {
    "code": "auth.unauthorized",
    "message": "Invalid or missing API key",
    "correlation_id": "..."
  }
}

403Forbidden

The API key is valid but doesn't have permission to access the requested resource.

{
  "error": {
    "code": "auth.forbidden",
    "message": "Access forbidden",
    "correlation_id": "..."
  }
}

400Bad Request

The request is valid but cannot be processed due to business logic constraints. This differs from 422 (validation errors) - 400 indicates the operation itself is not allowed.

Example: Invalid session type operation

{
  "error": {
    "code": "session.invalid-type",
    "message": "This operation is not allowed for this session type",
    "correlation_id": "..."
  }
}

Example: Session already confirmed

{
  "error": {
    "code": "session.already-confirmed",
    "message": "Session has already been confirmed",
    "correlation_id": "..."
  }
}

Other 400 error codes: session.campaign-not-available, session.cannot-confirm-expired, allocations.required, session.interactive-must-use-choose-campaign, session.non-interactive-cannot-choose-campaign, session.non-interactive-requires-allocations, session.interactive-cannot-have-allocations, session.interactive-session-requires-amount

404Not Found

The requested resource doesn't exist or doesn't belong to your organization. Each resource type has its own error code.

{
  "error": {
    "code": "customer.not-found",
    "message": "Customer not found",
    "correlation_id": "..."
  }
}

Other 404 error codes: vendor.not-found, session.not_found, donation-intent.not-found

410Gone

The session has expired. Create a new session to continue.

{
  "error": {
    "code": "session.expired",
    "message": "Session has expired",
    "correlation_id": "..."
  }
}

422Unprocessable Entity

The request body contains validation errors. Check the details object for field-specific validation messages.

{
  "error": {
    "code": "validation.failed",
    "message": "Validation failed",
    "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      "name": [
        "The name field is required."
      ],
      "campaign_identifier": [
        "The selected campaign is invalid."
      ]
    }
  }
}

Best Practices

Always check the HTTP status code first
Log correlation_id for all errors - it's included in every error response
Check the error.code field to handle specific error types programmatically
Handle 422 errors by displaying field-specific validation messages from the details object
Handle 400 errors by showing user-friendly messages about business logic constraints
For 401/403 errors, prompt users to check their API credentials
For 410 errors on sessions, create a new session