Error Handling

Every error response includes a machine-readable error_code you can switch on, and an error_type category for generic handling. See the full error code catalog for all codes and their meanings.

Error Response Shape

{
  "success": false,
  "error": "Human-readable message",
  "error_code": "specific_error_code",
  "error_type": "invalid_request_error",
  "request_id": "req_abc123"
}

Handling Errors

Switch on error_code for specific cases. Fall back to error_type for generic behavior.

Python

resp = requests.post(f"{BASE_URL}/api/reports", headers=headers, json=body)

if resp.status_code >= 400:
    err = resp.json()
    code = err.get("error_code", "")

    if code == "occupants_missing":
        print("Add occupants before generating a report.")
    elif code == "unsupported_file_type":
        print("Please upload a JPEG, PNG, or PDF.")
    elif err.get("error_type") == "api_error":
        # Server error — retry with backoff
        time.sleep(5)
    else:
        print(f"Error: {err['error']}")

TypeScript

const resp = await fetch(`${BASE_URL}/api/reports`, { ... });

if (!resp.ok) {
  const err = await resp.json();
  switch (err.error_code) {
    case "occupants_missing":
      console.error("Add occupants before generating a report.");
      break;
    case "unsupported_file_type":
      console.error("Please upload a JPEG, PNG, or PDF.");
      break;
    default:
      if (err.error_type === "api_error") {
        // Server error — retry with backoff
      } else {
        console.error(`Error: ${err.error}`);
      }
  }
}

Go

if resp.StatusCode >= 400 {
    var errResp struct {
        Error     string `json:"error"`
        ErrorCode string `json:"error_code"`
        ErrorType string `json:"error_type"`
    }
    json.NewDecoder(resp.Body).Decode(&errResp)

    switch errResp.ErrorCode {
    case "occupants_missing":
        log.Println("Add occupants before generating a report.")
    case "unsupported_file_type":
        log.Println("Please upload a JPEG, PNG, or PDF.")
    default:
        if errResp.ErrorType == "api_error" {
            // Server error — retry with backoff
        } else {
            log.Printf("Error: %s", errResp.Error)
        }
    }
}

Retry Strategy

• Retry api_error types (5xx) and 429 responses with exponential backoff
• Don't retry invalid_request_error types (4xx) — fix the request first
• Log the request_id — include it when contacting support

Further Reading

• Error Code Catalog — All error codes, HTTP statuses, and troubleshooting
• Polling Best Practices — Handle async report failures
• Rate Limiting — 429 handling and backoff