Error Handling

This page covers common error scenarios and how to handle them.

Authentication Errors

Missing Authorization Header

Request:

curl -X POST https://yourdomain.com/api/{partner}/lead/create \
  -H "Content-Type: application/json" \
  -d '{...}'

Response: 401 Unauthorized

{
  "message": "Unauthorized"
}

Invalid Token

Response: 401 Unauthorized

{
  "message": "Unauthorized"
}

Method Errors

Wrong HTTP Method

Request:

curl -X GET https://yourdomain.com/api/{partner}/lead/create \
  -H "Authorization: Bearer your_secret_key_here"

Response: 405 Method Not Allowed

{
  "message": "Method not allowed"
}

Validation Errors

Condo Without Unit Number

When buildingType is "condo", address.unitNumber is required.

Request:

curl -X POST https://yourdomain.com/api/{partner}/lead/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_key_here" \
  -d '{
    "buildingType": "condo",
    "loanPurpose": "homeImprovement",
    "propertyUsage": "primaryResidence",
    "contactInfo": {
      "firstName": "Alice",
      "lastName": "Brown",
      "email": "alice.brown@example.com",
      "phone": "+1-555-333-4444"
    },
    "address": {
      "street": "200 High Rise Ave",
      "city": "Miami",
      "state": "FL",
      "zip": "33101"
    },
    "residentialAddress": {
      "street": "200 High Rise Ave",
      "city": "Miami",
      "state": "FL",
      "zip": "33101"
    },
    "listedForSaleIn6Months": false,
    "purchasedOrSubjectToMortgageIn6Months": false,
    "liabilitiesIn4Years": false
  }'

Response: 400 Bad Request

{
  "error": {
    "issues": [
      {
        "code": "custom",
        "message": "Required for condo properties",
        "path": ["address", "unitNumber"]
      }
    ]
  }
}

Multi-Unit Without Property Units

When buildingType is "multiUnit", propertyUnits is required.

Request:

curl -X POST https://yourdomain.com/api/{partner}/lead/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_key_here" \
  -d '{
    "buildingType": "multiUnit",
    "loanPurpose": "investment",
    "propertyUsage": "investment",
    "contactInfo": {
      "firstName": "Charlie",
      "lastName": "Davis",
      "email": "charlie.davis@example.com",
      "phone": "+1-555-555-6666"
    },
    "address": {
      "street": "300 Complex Dr",
      "city": "Austin",
      "state": "TX",
      "zip": "73301"
    },
    "statedInformation": {
      "monthlyRentalIncome": 3000,
      "rentalOccupancy": "longTerm"
    },
    "residentialAddress": {
      "street": "400 Home St",
      "city": "Austin",
      "state": "TX",
      "zip": "73302"
    },
    "listedForSaleIn6Months": false,
    "purchasedOrSubjectToMortgageIn6Months": false,
    "liabilitiesIn4Years": false
  }'

Response: 400 Bad Request

{
  "error": {
    "issues": [
      {
        "code": "custom",
        "message": "Required for multi-unit properties",
        "path": ["propertyUnits"]
      }
    ]
  }
}

Investment Property Without Rental Occupancy

When propertyUsage is "investment", statedInformation.rentalOccupancy is required.

Request:

curl -X POST https://yourdomain.com/api/{partner}/lead/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_key_here" \
  -d '{
    "buildingType": "singleFamily",
    "loanPurpose": "investment",
    "propertyUsage": "investment",
    "contactInfo": {
      "firstName": "Diana",
      "lastName": "Evans",
      "email": "diana.evans@example.com",
      "phone": "+1-555-777-8888"
    },
    "address": {
      "street": "500 Rental Rd",
      "city": "Denver",
      "state": "CO",
      "zip": "80201"
    },
    "residentialAddress": {
      "street": "600 Owner Ave",
      "city": "Denver",
      "state": "CO",
      "zip": "80202"
    },
    "listedForSaleIn6Months": false,
    "purchasedOrSubjectToMortgageIn6Months": false,
    "liabilitiesIn4Years": false
  }'

Response: 400 Bad Request

{
  "error": {
    "issues": [
      {
        "code": "custom",
        "message": "Required for investment properties",
        "path": ["statedInformation", "rentalOccupancy"]
      }
    ]
  }
}

Investment Property Without Monthly Rental Income

When propertyUsage is "investment" and rentalOccupancy is NOT "vacant", monthlyRentalIncome is required.

Request:

curl -X POST https://yourdomain.com/api/{partner}/lead/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_key_here" \
  -d '{
    "buildingType": "singleFamily",
    "loanPurpose": "investment",
    "propertyUsage": "investment",
    "contactInfo": {
      "firstName": "Frank",
      "lastName": "Green",
      "email": "frank.green@example.com",
      "phone": "+1-555-999-0000"
    },
    "address": {
      "street": "700 Investment Ln",
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85001"
    },
    "statedInformation": {
      "rentalOccupancy": "longTerm"
    },
    "residentialAddress": {
      "street": "800 Living St",
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85002"
    },
    "listedForSaleIn6Months": false,
    "purchasedOrSubjectToMortgageIn6Months": false,
    "liabilitiesIn4Years": false
  }'

Response: 400 Bad Request

{
  "error": {
    "issues": [
      {
        "code": "custom",
        "message": "Required for non-vacant investment properties",
        "path": ["statedInformation", "monthlyRentalIncome"]
      }
    ]
  }
}

Invalid Email Format

Request:

curl -X POST https://yourdomain.com/api/{partner}/lead/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_key_here" \
  -d '{
    "buildingType": "singleFamily",
    "loanPurpose": "debtConsolidation",
    "propertyUsage": "primaryResidence",
    "contactInfo": {
      "firstName": "Henry",
      "lastName": "Jackson",
      "email": "not-an-email",
      "phone": "+1-555-444-5555"
    },
    "address": {
      "street": "1000 Bad Email St",
      "city": "Portland",
      "state": "OR",
      "zip": "97201"
    },
    "residentialAddress": {
      "street": "1000 Bad Email St",
      "city": "Portland",
      "state": "OR",
      "zip": "97201"
    },
    "listedForSaleIn6Months": false,
    "purchasedOrSubjectToMortgageIn6Months": false,
    "liabilitiesIn4Years": false
  }'

Response: 400 Bad Request

{
  "error": {
    "issues": [
      {
        "validation": "email",
        "code": "invalid_string",
        "message": "Invalid email",
        "path": ["contactInfo", "email"]
      }
    ]
  }
}

Duplicate Errors

Email Already in Use (Quote Exists)

When a quote with the same email already exists.

Response: 400 Bad Request

{
  "error": "Email already in use"
}

User Already Exists

When a user account with the same email already exists.

Response: 400 Bad Request

{
  "error": "User with this email already exists"
}

Error Handling Best Practices

Always check the status code first - Different status codes require different handling
Parse the error response - Look for message or error fields
Handle validation errors gracefully - Display specific field errors to users
Implement retry logic - For 500 errors, implement exponential backoff
Log errors for debugging - Include the full response body in logs
Check for duplicates before submission - If possible, verify email uniqueness on your end first