Error Handling

The API validates all inputs before processing. When validation fails, you'll receive detailed error messages explaining exactly what's wrong and how to fix it.

Error Response Format

All validation errors return HTTP 400 with this structure:

Code
 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": [
      { "field": "L_X", "message": "Expected number, received string" },
      { "field": "supports", "message": "At least 2 supports are required" }
    ]
  }
}

The details array contains one entry per validation issue, with:

• field - The attribute path (e.g., "supports.0.2" for nested values)
• message - Human-readable description of the problem

---

Common Validation Errors

Type Errors

Wrong type for numeric fields:

Code
 
// Wrong - string instead of number
{ "L_X": "14" }

// Correct
{ "L_X": 14 }

Error: Expected number, received string

Wrong type for Yes/No fields:

Code
 
// Wrong - boolean instead of string
{ "incSW": true }

// Correct
{ "incSW": "Yes" }

Error: Invalid enum value. Expected 'Yes' | 'No', received true

---

Enum Errors (Case-Sensitive)

All enum values are case-sensitive. Common mistakes:

Wet condition:

Code
 
// Wrong
{ "wet": "wet" }
{ "wet": "WET" }

// Correct
{ "wet": "Wet" }

Valid values: "Dry", "Wet"

Member type:

Code
 
// Wrong
{ "type": "database" }

// Correct
{ "type": "Database" }

Valid values: "Database", "Custom"

Support types:

Code
 
// Wrong
["pinned", 0, 1.5]

// Correct
["Pinned", 0, 1.5]

Valid values: "Pinned", "Roller", "Fixed"

Temperature:

Code
 
// Wrong
{ "T": "100" }

// Correct
{ "T": "T ≤ 100°F" }

Valid values: "T ≤ 100°F", "100°F < T ≤ 125°F", "125°F < T ≤ 150°F"

---

Range Errors

Zero or negative values:

Code
 
// Wrong
{ "L_X": 0 }
{ "L_X": -14 }
{ "spacing": -16 }

// Correct
{ "L_X": 14 }
{ "spacing": 16 }

Error: Beam length (L_X) must be positive

Non-integer where integer required:

Code
 
// Wrong - n_com must be integer
{ "n_com": 2.5 }

// Correct
{ "n_com": 2 }

Error: Number of plies (n_com) must be an integer

---

Array Structure Errors

Supports - minimum 2 required:

Code
 
// Wrong
{ "supports": [["Pinned", 0, 1.5]] }

// Correct
{ "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]] }

Error: At least 2 supports are required

Supports - incorrect tuple format:

Code
 
// Wrong - missing bearing width
["Pinned", 0]

// Wrong - string instead of number
["Pinned", "0", 1.5]

// Correct
["Pinned", 0, 1.5]

Format: [SupportType, position_ft, bearing_in]

Bearing width must be positive:

Code
 
// Wrong
["Pinned", 0, 0]

// Correct
["Pinned", 0, 1.5]

Error: Bearing width must be positive

---

Cross-Field Validation Errors

Database type requires member:

Code
 
// Wrong - missing member when type is Database
{
  "type": "Database",
  "L_X": 14,
  "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]]
}

// Correct
{
  "type": "Database",
  "member": "2x10 D.Fir-L No. 1",
  "L_X": 14,
  "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]]
}

Error: Field 'member' is required when type='Database'

Custom type requires dimensions:

Code
 
// Wrong - missing dimensions
{
  "type": "Custom",
  "L_X": 14,
  "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]]
}

// Correct
{
  "type": "Custom",
  "b_input": 1.5,
  "d_input": 9.25,
  "species": "Douglas Fir-Larch",
  "L_X": 14,
  "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]]
}

Errors:

• Field 'b_input' (width) is required when type='Custom'
• Field 'd_input' (depth) is required when type='Custom'
• Field 'species' is required when type='Custom'

Flitch beam requires flitch options:

Code
 
// Wrong
{
  "flitch": "Yes",
  "L_X": 14,
  "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]]
}

// Correct
{
  "flitch": "Yes",
  "n_flitch": 2,
  "t_flitch": 0.375,
  "L_X": 14,
  "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]]
}

Error: Fields 'n_flitch' and 't_flitch' are required when flitch='Yes'

---

Error Codes Reference

Code	HTTP Status	Description
VALIDATION_ERROR	400	Input validation failed
SHEET_NOT_FOUND	404	Sheet ID doesn't exist
PROJECT_NOT_FOUND	404	Project ID doesn't exist
CALCULATION_ERROR	422	Calculation failed (check inputs)
UPSTREAM_ERROR	500	Internal server error

---

Debugging Tips

1. Check the details array - Each entry tells you exactly which field failed and why
2. Nested paths - supports.0.2 means "first support, third element (bearing width)"
3. Case sensitivity - All enum values are case-sensitive ("Wet" not "wet")
4. Types matter - Numbers must be numbers, not strings (14 not "14")
5. Use the API reference - Interactive docs show exact expected types

---

Next Steps

• Attributes Reference - Valid values for all fields
• API Reference - Interactive endpoint testing